Files
PaperClipAI/doc/STORYBOOK-DEPLOYMENT.md
T
DottaandClaude Fable 5.2 ac114d9479 refactor: cut DEVELOPING.md to a setup and workflow guide (#21670)
## 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>
2026-11-14 18:02:27 -06:00

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, region us-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.