PaperClipAI/doc/plans/chat-adapters/setup-wireframe-data-v8.mjs

import { setupFlows as v6SetupFlows } from "./setup-wireframe-data-v6.mjs";

const githubSetup = {
  provider: "GitHub",
  short: "GitHub",
  screens: [
    {
      id: "16",
      slug: "github-create",
      title: "Create or connect a GitHub App",
      subtitle:
        "Bring your own dedicated GitHub App and verify it with Paperclip.",
      rail: ["Agent selected", "Connect GitHub App", "Try Maya"],
      active: 1,
      mode: "default",
      instructions: [
        [
          "Generate the webhook secret",
          "Paperclip stores a random 32-byte secret and shows it once. Paste it with the Paperclip webhook URL into GitHub and keep SSL verification enabled.",
        ],
        [
          "Set minimum permissions and events",
          "Grant Metadata: read, Issues: read and write, and Pull requests: read and write. Subscribe only to Issue comment and Pull request review comment.",
        ],
        [
          "Create and install the App",
          "Choose the owning user or organization, keep user authorization off, then install the App on only the repositories where people may mention the agent.",
        ],
        [
          "Return the App credentials",
          "Paste the numeric App ID and private-key PEM into Paperclip. Connect remains unavailable until GitHub has delivered a correctly signed webhook ping.",
        ],
      ],
      values: [
        [
          "Paperclip webhook URL",
          "https://paperclip.example/api/chat-webhooks/…/github",
        ],
        ["Webhook secret", "Generated by Paperclip · shown once"],
      ],
      fields: [
        ["GitHub App ID", "123456"],
        ["Private key (PEM)", "Write-only PEM"],
      ],
      actions: [
        [
          "Generate webhook secret",
          "Creates and stores the webhook secret, then exposes its one-time copy value.",
        ],
        [
          "Open new GitHub App form",
          "Opens GitHub App registration; GitHub remains the authority for App ownership and repository installation.",
        ],
        [
          "Connect and verify",
          "Authenticates with the App ID and private key, verifies the immutable App identity, required permissions and events, installation, and signed webhook ping.",
        ],
      ],
      annotations: [
        "The customer-owned App path is the complete shipped setup; no managed App Manifest exchange is required.",
        "Paperclip generates the webhook secret and never returns it from normal endpoint reads.",
        "Grant Metadata read, Issues and Pull requests read/write, plus Issue comment and Pull request review comment events; installation lifecycle events are automatic.",
        "GitHub installation scope and Paperclip repository enablement remain independent reach controls.",
      ],
      rationale:
        "Bring-your-own App credentials are sufficient to ship and preserve one provider bot identity per Paperclip agent.",
    },
    {
      id: "46",
      slug: "github-try",
      title: "Try Maya in GitHub",
      subtitle: "Start one task in an installed repository.",
      rail: ["Agent selected", "Connect GitHub App", "Try Maya"],
      active: 2,
      mode: "default",
      instructions: [
        [
          "Open an issue or pull request",
          "Use one of the repositories selected in the customer-owned App installation.",
        ],
        [
          "Mention Maya",
          "Add a comment that directly mentions the verified GitHub App bot.",
        ],
        [
          "Continue the task",
          "Add another comment in the same issue or pull request without repeating the mention.",
        ],
      ],
      actions: [
        [
          "Open GitHub",
          "Opens an installed repository while Paperclip waits for the first signed mention and follow-up to complete setup.",
        ],
      ],
      annotations: [
        "The test uses the real GitHub issue or pull-request conversation boundary.",
        "The first addressed setup repository becomes enabled; other discovered repositories remain disabled.",
        "One external conversation maps to one Paperclip task.",
      ],
      rationale:
        "A signed provider round trip proves installation, reach, identity, and conversation continuity.",
    },
  ],
};

// v8 also replaced the helper-first Teams draft. Keep the current generator
// from overwriting that settled customer-owned setup while it consumes the
// historical v6 data for unchanged providers.
const teamsSetup = {
  provider: "Microsoft Teams",
  short: "Teams",
  screens: [
    {
      id: "19",
      slug: "teams-register",
      title: "Create Maya for Microsoft Teams",
      subtitle: "Register a customer-owned Entra App and Azure Bot.",
      rail: ["Agent selected", "Connect Teams app", "Install Maya", "Try Maya"],
      active: 1,
      mode: "default",
      instructions: [
        [
          "Copy the messaging endpoint",
          "Use Paperclip's public callback in the Azure Bot configuration.",
        ],
        [
          "Create the Microsoft resources",
          "Create the single-tenant Entra App, client secret, Azure Bot, and customer-owned Teams app in Microsoft's portals.",
        ],
        [
          "Return the identity values",
          "Paste the Application ID, Directory/Tenant ID, and client-secret value into Paperclip.",
        ],
      ],
      actions: [
        [
          "Copy messaging endpoint",
          "Copies the public callback for Azure Bot configuration.",
        ],
        [
          "Open Microsoft setup",
          "Opens Microsoft's provider-owned registration surfaces.",
        ],
        [
          "Connect and verify",
          "Stores the client secret write-only and verifies the tenant and application identity.",
        ],
      ],
      annotations: [
        "Paperclip provides the exact public messaging endpoint.",
        "The operator creates the single-tenant Entra App, Azure Bot, and Teams app in Microsoft.",
        "A future helper is optional and cannot gate the customer-owned path or release.",
      ],
      rationale:
        "Bring-your-own credentials are the required portable setup path.",
    },
    {
      id: "49",
      slug: "teams-install",
      title: "Install Maya in Microsoft Teams",
      subtitle:
        "Publish or upload the customer-owned app, then add it in Teams.",
      rail: ["Agent selected", "Connect Teams app", "Install Maya", "Try Maya"],
      active: 2,
      mode: "default",
      instructions: [
        [
          "Open Teams Developer Portal",
          "Complete the app metadata and publish it or download it for tenant-approved custom upload.",
        ],
        [
          "Install the app",
          "Use Microsoft's installation flow in the intended personal, team, or group-chat scope.",
        ],
      ],
      actions: [
        [
          "Open Teams Developer Portal",
          "Opens the provider-owned app surface; tenant policy may require administrator approval.",
        ],
      ],
      annotations: [
        "Microsoft owns app creation, packaging, publication, approval, and installation.",
        "Paperclip does not generate a complete Teams package or promise an install link.",
        "Tenant approval remains in Microsoft's install experience.",
      ],
      rationale:
        "Customer-owned registration is required; Microsoft owns the app artifact and installation.",
    },
    {
      id: "50",
      slug: "teams-try",
      title: "Try Maya in Microsoft Teams",
      subtitle: "Start one task in a channel post.",
      rail: ["Agent selected", "Connect Teams app", "Install Maya", "Try Maya"],
      active: 3,
      mode: "default",
      instructions: [
        [
          "Open an installed channel",
          "Start a new post rather than replying to an unrelated post.",
        ],
        ["Mention Maya", "Mention the installed bot in the new post."],
        [
          "Continue in replies",
          "Reply once beneath that post; the post and replies are one Paperclip task.",
        ],
      ],
      actions: [
        [
          "Open Microsoft Teams",
          "Opens Teams while Paperclip waits for the authenticated mention and reply.",
        ],
      ],
      annotations: [
        "The body is only the Teams channel test sequence.",
        "The instructions teach the channel-post-and-replies task boundary.",
        "There is one action: open Teams and perform the test.",
      ],
      rationale: "The final provider event is the verification.",
    },
    {
      id: "48",
      slug: "teams-manual",
      title: "Microsoft provider setup details",
      subtitle:
        "Create the customer-owned bot and app, then paste the three identity values.",
      rail: ["Agent selected", "Connect Teams app", "Install Maya", "Try Maya"],
      active: 1,
      mode: "default",
      instructions: [
        [
          "Create the Microsoft identity",
          "Create a single-tenant Entra App registration and a client secret.",
        ],
        [
          "Create the bot and Teams app",
          "Create the Azure Bot, configure Paperclip's endpoint, and create the customer-owned Teams app in Developer Portal.",
        ],
        [
          "Enter the identity below",
          "Return the Application ID, Directory ID, and client-secret value to Paperclip.",
        ],
      ],
      actions: [
        [
          "Copy Paperclip endpoint",
          "Copies the public messaging endpoint for the Azure Bot resource.",
        ],
        [
          "Connect and verify",
          "Stores the client secret write-only and verifies Microsoft bot authentication.",
        ],
        ["Back", "Returns to the primary customer-owned credential setup."],
      ],
      annotations: [
        "The endpoint is the one Paperclip-specific value required by Microsoft.",
        "Every instruction is a provider portal operation.",
        "The three identity fields are the minimum credentials Paperclip needs.",
        "Connect does not generate a Teams package or install link.",
      ],
      rationale:
        "This is reference detail for the required customer-owned path; a future helper remains optional.",
    },
  ],
};

export const setupFlows = v6SetupFlows.map((flow) =>
  flow.provider === "GitHub"
    ? githubSetup
    : flow.provider === "Microsoft Teams"
      ? teamsSetup
      : flow,
);