## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - `AGENTS.md` tells every contributor and agent to read `doc/DEVELOPING.md` for setup, commands, testing, and worktrees > - That file grew to 5,495 lines. Most of it was notes on how one subsystem behaves, added one pull request at a time > - Readers could not find the commands. Agents also read behavior notes as rules > - This pull request cuts `doc/DEVELOPING.md` to a 660-line setup and workflow guide. It moves the subsystem notes to focused docs > - The benefit is a guide that a person or an agent can read in full, and a clear place for each kind of note ## Linked Issues or Issue Description **Issue type** Outdated or confusing documentation. **Where is the issue?** `doc/DEVELOPING.md` **What's wrong?** The file was 5,495 lines. It opened with 112 lines about case handoffs before it reached Prerequisites. Unrelated sections sat below the "OpenClaw Docker UI One-Command Script" heading. Statements about current behavior read like policy. **Suggested fix** Keep setup, commands, and workflow in `doc/DEVELOPING.md`. Move each subsystem note to a doc for that subsystem. Add an index. ## What Changed - `doc/DEVELOPING.md` is now 660 lines: prerequisites, start dev, health checks, local run, test drive, Docker, instance layout, database, storage, secrets, worktrees, test commands, Storybook, CLI, and an index of the other docs. - 15 new docs hold the moved text without wording changes: `ci-workflows`, `test-infrastructure`, `worktrees`, `hot-restart-deploys`, `heartbeat-internals`, `runner-internals`, `workspace-repositories`, `workspace-storage`, `skills-and-teams-catalog`, `ui-internals`, `case-handoffs`, `chat-connector-development`, `instance-configuration`, `integration-api-notes`, `database-backups`. - "Publish a branch Storybook" moved to `doc/STORYBOOK-DEPLOYMENT.md`. The privacy rollout notes moved to `doc/ISSUE-PRIVACY.md`. - Deleted about 280 lines: the story-by-story Storybook notes, "Agent Artifact Uploads" (a copy of `doc/AGENT-ARTIFACTS.md`), two pointer-only sections, "Workspace feature checks (2026-10-09)", and "Chat and task navigation caching". The test-drive build-lock paragraph is now four lines. - Repointed every inbound link and every script or workflow comment that named a moved section. - `AGENTS.md` now says where a behavior note goes, so the guide does not grow again. ## Verification - A script split the file by line range. It asserts that each of the 5,495 source lines is kept, moved, or dropped exactly one time. - A link check on every changed Markdown file found 0 missing files and 0 missing anchors. - `node scripts/check-maps.mjs` passes. - `node --test .github/scripts/tests/*.test.mjs`: 808 pass, 0 fail. - `node --check` passes on the three scripts with changed comments. - `pnpm verify` was not run. This worktree has no installed dependencies, and the change has no runtime code. ## Risks - Low risk. The change is documentation and comments only. - A link to a moved section from outside this repository will land on the top of `doc/DEVELOPING.md`. - The new docs are not in the audited prose list in `.github/scripts/ci-inputs.mjs`. An edit to one of them runs full CI. An edit to `doc/DEVELOPING.md` does not. This PR does not change that list. ## Model Used - Claude Fable 5.2 (`claude-fable-5-2`), Claude Code desktop, with tool use. ## 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 - [ ] 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 - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
8.0 KiB
Storybook branch hosting
The Storybook Deploy workflow publishes public static Storybook builds to the
existing private S3 bucket behind CloudFront. It does not deploy to GitHub Pages.
Current destination
- AWS account:
078455283791, regionus-east-1 - Bucket:
paperclipai-runner-e2e-history-078455283791-us-east-1 - Allowed upload prefix:
storybook/branches/ - Distribution:
E3GTU28BBO2SFR - Public origin:
https://d1p6rlowie26tp.cloudfront.net - Role:
arn:aws:iam::078455283791:role/paperclip-storybook-github
The distribution's default behavior disables edge caching and rewrites directory
URLs to index.html. Stable branch indexes send no-cache; unique build objects
send immutable. No invalidations or CloudFront write permissions are needed.
Each publication updates a readable bookmark, such as
https://d1p6rlowie26tp.cloudfront.net/storybook/branches/master/, after the
immutable build upload completes. It also updates the previous hashed branch
entry for compatibility. The run summary and Markdown artifact link the bookmark.
Branch names use one escaped path segment, preserving case and separating slashes
from hyphens; see the branch publishing guide
for the encoding. No additional AWS permissions or distribution changes are needed.
GitHub configuration
Create environment storybook-deploy with required reviewers set to the
individual CODEOWNERS accounts. Disable administrator bypass, allow self-review,
and allow repository branches. Keep these reviewers synchronized with CODEOWNERS.
The workflow rejects environments with no required reviewers, non-owner reviewers
or administrator bypass enabled. The AWS role trusts only this repository and
this environment, so a branch cannot obtain upload access through an unprotected
environment.
Set repository variables:
| Variable | Value |
|---|---|
STORYBOOK_AWS_ROLE_ARN |
arn:aws:iam::078455283791:role/paperclip-storybook-github |
STORYBOOK_AWS_REGION |
us-east-1 |
STORYBOOK_S3_BUCKET |
paperclipai-runner-e2e-history-078455283791-us-east-1 |
STORYBOOK_PUBLIC_BASE_URL |
https://d1p6rlowie26tp.cloudfront.net |
No stored AWS access keys are needed. Leave the runner dashboard variables and GitHub Pages configuration unchanged.
Operator setup
Use the paperclip-dev operator AWS profile. Review the checked-in policies in
.github/storybook-deploy/ before applying them. The existing GitHub OIDC provider
must be present in this account.
aws sts get-caller-identity --profile paperclip-dev
aws iam create-role --profile paperclip-dev \
--role-name paperclip-storybook-github \
--assume-role-policy-document file://.github/storybook-deploy/trust-policy.json
aws iam put-role-policy --profile paperclip-dev \
--role-name paperclip-storybook-github --policy-name StorybookBranchUpload \
--policy-document file://.github/storybook-deploy/upload-policy.json
For an existing role, use update-assume-role-policy instead of create-role.
Add the statement from cloudfront-read-statement.json to the existing bucket
policy's Statement array. Preserve every other statement, including the HTTPS
requirement and runner report access. Keep all S3 public-access blocks enabled;
only CloudFront receives read access to this public-content prefix.
The role has no delete, bucket policy, IAM, CloudFront, or root-object permissions.
The workflow never runs sync --delete. Builds accumulate; any retention cleanup
must preserve the build referenced by each branch entry.
Verification
node --test scripts/__tests__/storybook-deploy.test.mjs
actionlint .github/workflows/storybook-deploy.yml .github/workflows/storybook-visual.yml
Dispatch two source branches, approve each deployment, and check their distinct
branch URLs and each build's deployment.json. Redeploy one branch and confirm
its stable URL now points to the new build while the other branch is unchanged.
The publisher checks the public build metadata against the selected source SHA
and verifies that the public branch entry points to this exact build. It retries
brief propagation delays and fails if the branch URL remains stale.
Publish a branch Storybook
CODEOWNERS can publish a repository branch through Actions → Storybook Deploy →
Run workflow. Keep the workflow branch on master and enter the source branch
in branch. The source branch does not need to contain the workflow. Leaving
branch empty publishes the selected workflow branch's dispatched commit.
gh workflow run storybook-deploy.yml --ref master -f branch=your-branch
The existing Storybook Visual workflow also offers a deploy_preview checkbox,
which publishes through the same workflow instead of running visual tests:
gh workflow run storybook-visual.yml --ref master -f deploy_preview=true -f branch=your-branch
Approve the storybook-deploy environment as a CODEOWNER. The workflow summary
links the stable branch URL and this build. The run also uploads a
storybook-deployment-<run-id>-<attempt> artifact containing
storybook-deployment.md with both links and the source commit. Different branches have
different URLs; publishing one never replaces another. Redeploying the same
branch updates its stable URL only after all files for the new build are uploaded.
Previous build links keep working. The branch entry preserves Storybook query
parameters and fragments when redirecting to the completed build.
Bookmark URLs use storybook/branches/<branch>/, for example
https://d1p6rlowie26tp.cloudfront.net/storybook/branches/master/.
Copy the stable branch URL from the run summary when saving a bookmark;
opening it redirects to the latest published build. Branch names preserve case.
Characters other than letters, digits, _, and - use ~HH UTF-8 escapes, so
feature/foo becomes feature~2Ffoo and stays distinct from feature-foo.
Names ending in a hyphen and 16 lowercase hex digits escape that hyphen to
reserve the existing build directories. Very long names use a hash suffix.
Existing hashed branch URLs keep updating and remain valid. Build files remain
under storybook/branches/<readable-branch>-<hash>/builds/<run-id>-<attempt>/.
deployment.json in each build records its branch, source commit and URLs.
Builds run independently; publication is serialized per branch. Retained builds
are not automatically deleted and will accumulate until an operator prunes them.
Publishing requires both the original actor and the current rerunner to be
individual GitHub accounts named in .github/CODEOWNERS on the current default
branch. Individual accounts from every ownership rule are included, regardless
of which paths they own. Comments, teams and email entries do not grant access.
Authorization runs before the build and again before deployment, including
deployment-only reruns.
GitHub also requires a CODEOWNER environment approval, so editing authorization
code on a branch cannot grant AWS access without an authorized reviewer.
CODEOWNERS membership does not automatically add an account to the environment's
required reviewers; a configured reviewer must approve each deployment.
The build downloads the public source archive with no GitHub token permissions,
AWS credentials or repository secrets. Dependency caching and install lifecycle
scripts are disabled. The separate publisher uses GitHub OIDC to assume a role limited to
storybook/branches/*. It treats the build artifact as static files and runs only
the publisher from the workflow checkout. It cannot delete objects, change AWS
settings, or overwrite the runner dashboard. The Storybook site itself is public.
Pushes and PR events never publish it.
The existing S3 bucket and CloudFront distribution also serve runner reports in separate prefixes. GitHub Pages and its dashboard workflow are independent. See the setup sections above for the environment, repository variables, AWS policies and one-time operator setup.
GitHub requires a new dispatch workflow to exist on the default branch before it becomes a manual entry point.