mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 18:26:40 +01:00
## 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>
156 lines
8.0 KiB
Markdown
156 lines
8.0 KiB
Markdown
# 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](#publish-a-branch-storybook)
|
|
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.
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
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.
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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.
|