Files
PaperClipAI/maps
ce27dde855 Start onboarding in chat and defer execution until the user chooses work (#22077)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Onboarding connects an agent and gives the user a place to discuss
work.
> - The previous flow created an execution task and project before the
user chose a scope.
> - A standing chat can gather the goal and clear exit criteria first.
> - This pull request opens chat after onboarding and starts a live
welcome after the chat is visible.
> - The agent proposes work for acceptance, or creates a task when the
user explicitly requests one.
> - Subscription setup and shared question state must work for this
first conversation to succeed.

## Linked Issues or Issue Description

**Subsystem affected**
Company onboarding, agent chat, local subscription setup, task
numbering, and shared interaction views.

**Problem or motivation**
The first session creates work before the user has agreed to a goal.
Standing chats consume task numbers. An answered chat question can
remain pending in the inbox. Claude code entry requires an extra click,
and switching from Claude to Codex can leave an incompatible model
selected.

**Proposed solution**
Open an owner-bound chat for every new company. Start a live welcome
after the chat paints in a visible tab. Gather scope in conversation and
use the existing task acceptance flow. Keep chat records out of the task
number sequence. Publish question responses to shared caches and cancel
stale reads. Submit pasted Claude codes once and wait for verified
sign-in before connecting.

**Alternatives considered**
A fixed welcome would not use the onboarding context. A hidden execution
task would still create work and consume a task number. Keep the
existing task proposal and acceptance contract instead.

**Roadmap alignment**
This improves the shipped Agent Chat and Personal & Shared AI Accounts
flows in ROADMAP.md. It does not add a separate execution or approval
system.

Related prior work: Refs #19643 and #19512. Related route handoff work:
Refs #12557. This change replaces the automatic first task with chat; it
also repairs the subscription and shared question state paths used
during that journey.

## What Changed

- Finish onboarding in agent chat for default and team-template
companies. Create no execution task or project.
- Queue one live welcome after visible chat content paints. Pass company
goals and the initial idea as context. Preserve access, budget, and
hiring controls.
- Instruct the agent to gather a goal and exit criteria, offer an
interview, and propose tasks for acceptance. Allow direct creation on an
explicit user request.
- Leave new standing chats unnumbered. The first execution task receives
number 1. Preserve existing identifiers.
- Synchronize answered question cards across chat and inbox, including
concurrent requests and inactive cached views.
- Submit a pasted Claude authorization code once. Show connection
progress and hide the restart link while sign-in is still preparing.
Detect rejected OAuth codes promptly. Clear incompatible models when the
provider changes.
- Use `Work with [agent name]` as the default chat composer placeholder.
- Add regression coverage and update onboarding documentation and API
notes.

## Verification

- Completed a real Claude subscription journey on macOS with an isolated
local database. Authorized the account, pasted the real code, and
reached the review step without clicking Submit code or Connect. Get
started opened chat and the live welcome run succeeded. The company had
zero execution tasks, zero projects, and task counter 0.
- On rebased commit c664949858, 6 browser cases passed for
paste-to-connect-to-chat, task-free onboarding, existing-company
routing, the native connection probe gate, desktop/mobile planning, and
two-tab chat/inbox question synchronization.
- On the rebased head, 419 focused UI tests passed. The focused server
and adapter run passed 160 tests and hit one `socket hang up` in the
existing authenticated chat route test. The full 72-test conversation
suite passed on one repeat. The cause of that first socket failure
remains unconfirmed; the passing repeat does not establish its cause.
- UI typecheck and server declaration typecheck pass after the rebase.
The first server check found a missing local dependency from master; a
frozen-lockfile install repaired it. No dependency manifest or lockfile
change was needed.
- The first Greptile review found two welcome edge cases. Four new tests
reproduced both before the fix. On commit b380f14ef9, all 114 onboarding
and queue tests pass, including timeout retries and queued welcomes
replaced by a user message or chat reset. Server source and focused test
type checks pass on this revision.
- [Greptile
review](https://github.com/paperclipai/paperclip/pull/22077#issuecomment-6961533641)
gives rebased commit 2dbad34445 a score of
5/5. The current-head check passed. Both welcome review threads are
resolved, with no new actionable findings.
- CI serialized shard 8/9 found a missing OpenAPI inventory entry for
the new route file. The exact coverage test reproduced this locally.
Commit 17a72ec8b7 adds explicit mounted paths and documents both
board-only operations. All 65 OpenAPI and onboarding route tests and
server source typecheck pass after the fix. The final CI run passes on
this revision.
- Rebased onto master 23ce68a8dc and regenerated the SDK source registry
from committed inputs. Worktree preflight, SDK source validation, and
all 65 API/onboarding tests pass on final head
2dbad34445.
- On final head 2dbad34445, all 419
affected UI tests pass. UI package typecheck and server declaration
typecheck also pass. Commands: `pnpm --filter @paperclipai/ui
typecheck`; `node server/scripts/typecheck-layers.mjs
--declarations-only`; focused Vitest suites for the wizard, subscription
login, agent chat, shared interaction cache, and OpenAPI/onboarding
routes.
- [Final-head CI
run](https://github.com/paperclipai/paperclip/actions/runs/44208652564)
completed successfully on commit
2dbad34445. All required typecheck, build,
test, Runner, browser, serialized-server, and canary gates pass,
including the [final verify
job](https://github.com/paperclipai/paperclip/actions/runs/44208652564/job/134487749343).
The fresh routing gate selected the trusted AWS fleet after the
protected owner policy in #22098 merged. No source rebase was needed:
the gate reads that policy from protected master.
- The repaired OpenAPI shard passed in the earlier same-head CI run.
General server shard 8/12 hit a 20-second step timeout in the existing
`issue-recovery-live-run-agent-census` suite. This PR does not change
that suite or its fixture. All four tests pass locally on the exact
current commit in 84 seconds. The cause of the CI timeout remains
unconfirmed. Every other test job passed. A single failed-shard retry
was accepted but remained queued on its saved GitHub-hosted selection.
It was cancelled before test execution after #22098 merged. The fresh
full-CI run passed on the unchanged head under the approved AWS policy,
including [server shard
8/12](https://github.com/paperclipai/paperclip/actions/runs/44208652564/job/134481388730).
This passing execution does not establish the cause of the earlier
timeout.
- Worktree preflight, committed SDK source input validation, and diff
whitespace checks pass after the rebase.
- `pnpm verify` reports exit 2 because the new subsystem documentation
requires broader CI coverage. The final successful CI run supplies that
broader coverage. This is not a full local suite pass.

## Risks

- The initial task is now an explicit user decision. Existing onboarding
tasks and numbered records remain readable. No schema migration is
required.
- A welcome still depends on a working provider connection and the
normal run queue. Failed starts can be retried without duplicate
successful welcomes.
- Claude paste acceptance was verified with a real subscription on
macOS. This change does not claim a new live Codex or Windows acceptance
test.

## Model Used

OpenAI Codex, based on GPT-6, with tool-assisted reasoning, code
execution, terminal checks, and browser verification. The client does
not expose the exact routed build or context limit.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Scott Tong <scott@scottsmbpm5max.lan>
Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-11-17 16:52:35 -08:00
..

Paperclip maps

The maps describe the same capabilities from two perspectives:

  • Feature map: what a person can do, where to reach it, and how to verify the user journey. Preserve its Poteto format.
  • Agent access map: the APIs and agent entry points for those capabilities, their permission boundaries, and access verification.

The chat scenario catalog adds natural-language requests, starting context and expected conversational outcomes for the same capability IDs. It lives with Product E2E as planning data; a scenario reference is neither a registered execution nor evidence that a journey passed.

These are sibling directories under maps/. Each feature file has a same-named agent access companion. Reuse the product map's sub-feature IDs, so tasks/create identifies the same capability in both maps. Product behavior remains governed by the code and its tests; a map cannot grant authority or redefine a permission denial as success.

Capability identifiers

The feature ID is the recipe filename without .md, such as onboarding. The full capability ID joins that feature ID and a Sub-features key with /: the company key in feature-map/onboarding.md is onboarding/company. Its agent-access-map/onboarding.md companion uses the same local company key. The feature-map index lists the existing feature and full capability IDs.

Each child page states Feature ID: `onboarding`. after its introduction or product-map link. In feature recipes, show the full ID beside the parsed local key: - `company`: `onboarding/company` — create a company. In access companions and Storybook verification guidance, keep the existing local heading and put Capability ID: `onboarding/company`. beneath it. These labels make the existing identifiers visible without changing keys, anchors, or ID generation.

Use full capability IDs in cross-feature references, Storybook annotations, tests, issues, PRs, and verification evidence. Both segments use lowercase letters, digits, and hyphens. Keep filenames and keys stable when display titles or navigation labels change; renaming either changes the capability ID.

Entry-point IDs describe a surface, such as web-wizard, and are scoped to their recipe. Reference them with a recipe link, such as onboarding.md#web-wizard, and record the capability exercised separately. Navigation section labels are not capability IDs. See IDs and references for examples.

Access contract

Every business operation needs both an API and a usable agent entry point for an actor authorized to perform it. A dedicated tool is optional when REST, the CLI, an assigned MCP client, or native search_api / call_api already provides the operation. Record which agent surfaces actually have that path; an installed CLI or optional MCP package cannot be assumed available to every native/remote run.

Track these independently:

Dimension Values and meaning
API present, missing, not-applicable, or unreviewed. Use exact methods/paths; distinguish protocols from REST.
Agent access available, partial, missing, restricted, operator-only, not-applicable, or unreviewed. Name the supported surface and actual entry point.
Policy Actor, action/grant, company/resource/ownership scope, responsible-user intersection, run requirements, work modes, and gates relevant to the operation.
Evidence source-only, verified, failed, blocked, or not-run. Source presence and successful board calls are not agent verification.
Review depth baseline records representative operations and known gaps; operation-reviewed enumerates the capability's meaningful operations and their individual access contracts.

Broad capabilities such as task properties must be split into operations before they count as operation-reviewed: renaming, metadata edits, assignment, dependencies, and lifecycle changes can use different tools and permission rules. An available read path cannot certify a write path. List/get/create/update/delete, execution/control, credential handling, and resolution are separate where their authority or transport differs. Do not duplicate request schemas from OpenAPI.

Exceptions and restrictions

Presentation-only state, static developer fixtures, and pre-start/local operator work may use not-applicable for a domain API, with a concrete reason and the existing local path. When a capability combines shared data with presentation, split the operations: browser recents do not exempt resource lookup from API coverage. Promoting local state to a shared feature requires revisiting the entry.

A board-only endpoint is restricted for agent identity, not an automatic exception or a missing API. Cite the enforced policy and record whether the agent can request the authorized human's action and observe its result. An unresolved delegation question remains in Gaps. Company access, a job title, a personal assistant's OAuth grant, or an accepted interaction does not grant board identity. Keep budget, approval, secret and execution authority intact.

Check actual route/service authorization and production tool admission. OpenAPI actor labels and scenario/evaluation tool declarations are supporting metadata; record disagreements rather than using them as proof of access. Native API fallback restrictions, tool field/scope limits, and rollout settings are part of the agent path, even when a legacy agent can call the REST endpoint directly.

Companion file format

Each agent-access-map/<area>.md has an H1, a relative link to its product file, and its feature ID, followed by one H2 backticked local key per product sub-feature. Each capability starts with its full capability ID and contains these fields:

  • Review: baseline or operation-reviewed.
  • API: presence state and exact operation IDs, or a reasoned exception.
  • Agent access: availability state and concrete entry points by surface.
  • Policy: relevant permission and runtime boundaries, with source references.
  • Evidence: evidence state, reviewed commit and sources or executed proof.
  • Verification: allowed/denied assertions and observable result; record what has actually run separately from the proposed recipe.
  • Gaps: missing APIs/paths, discovery drift, unreviewed operations or policy decisions; use none only for the enumerated scope that was reviewed.

For an operation-reviewed capability, use H3 backticked operation IDs and repeat API, Agent access, Policy, Evidence, Verification and Gaps for each operation. Use small operation names such as create, update, read, or run-now. The enclosing capability has Review: operation-reviewed only after its meaningful operations have been enumerated. The following excerpt shows one operation; include the others before using that review label:

## `definition`

Review: `operation-reviewed`.

### `create`

API: `present` — POST /api/companies/{companyId}/routines.
Agent access: `available` — agent REST, CLI routine create and native call_api
under the enabled rollout and active-run/mode gates.
Policy: same company; assigneeAgentId must be the calling agent; cite the
routine authorization and native API policy sources.
Evidence: `source-only` — reviewed commit and source links; no live proof.
Verification: `not-run` — create an owned routine; reject assignment to another
agent; inspect saved configuration, attribution and retry behavior.
Gaps: verify ownership and responsible-user resolution with a permitted agent
context; source presence alone does not qualify this operation.

Keeping the maps synchronized

Add entries only for substantial new features under the feature-map scope rule. Routine fixes, polish, refactors, performance work, and test changes do not require map updates. Correct or remove existing text only when behavior or access changes make it materially inaccurate; keep the correction local to the affected recipe or companion. Preserve IDs across renames where the capability is unchanged; update the affected cross-links together. Indexes discover recipes automatically. An API-only change may update the companion without rewriting unchanged user instructions. Update the corresponding chat scenarios when their request, assumptions or expected outcome changes; use multiple cases for meaningfully different starting conditions rather than treating an API path as conversational coverage.

maintain-verification-skill owns reconciliation of both maps. It follows changed source and authorization, checks real agent reachability, and records product gaps without implementing them during a maintenance pass. The creation skill uses this structure. verify-paperclip consumes the relevant recipes and reports evidence/drift; map editing belongs to maintenance.

Run the structural check after map changes:

node scripts/check-maps.mjs

It checks paired areas/IDs, navigation metadata, required fields, and local references. It does not certify endpoint authorization, production bindings, operation completeness, or live behavior. Source audits must check those against the existing API and tool contracts; avoid a second schema catalog or runtime.

For live access proof, use Paperclip's existing API/runner/MCP fixtures or an owned isolated instance. Use the actual agent identity, target and work mode. Assert the allowed result and relevant denial (another company/private resource, wrong owner, missing grant, invalid run, restricted mode or resolver). Mutations also need persisted state/attribution and retry behavior. Capture evidence using the existing artifact workflow; keep executed run results separate from generated maps/generated/coverage.json, which lists page references.

Local authorship and generated indexes

Change only the recipes, access contracts and stories whose behavior or intent changed. Feature recipes own navigation metadata; stories own small parameters.paperclip annotations. Keep the feature-map README's readable ID index aligned with those sources; it does not register entries for generation. Do not refresh counts in shared READMEs, inventories, fingerprints or review journals.

node scripts/storybook-catalog.mjs validates and generates aggregate navigation, Storybook data, verification routes and the page inventory. All outputs live in ignored maps/generated/, ui/storybook/generated/, and the ignored Storybook preview.tsx wrapper. Start/build and UI typechecking generate their own inputs. A clean merged checkout therefore assembles both branches' changes automatically.

Git provides history and diffs. PRs, issues and CI artifacts retain review/run evidence for the named revision. Capability associations do not create whole-file review dependencies. Keep durable scenario limits in the affected recipe or story.