paperclip-page

1---2name: paperclip-page3description: >4  Publish static HTML pages and asset folders to the Paperclip S3/CloudFront page5  host. Use when asked to deploy, host, or share a persistent page, viewer,6  prototype, report, or static site without here.now.7---8 9# Paperclip Page10 11Use this skill to publish a static directory to the configured Paperclip pages12host, for example `https://pages.paperclip.ing/<slug>/`.13 14## Requirements15 16- Source directory contains `index.html` at its root.17- `aws` CLI v2, `curl`, and `jq` are available on PATH for live publishes.18- Environment variables are configured:19  - `PAPERCLIP_PAGE_BUCKET`20  - `PAPERCLIP_PAGE_BASE_URL`21  - `AWS_REGION`22  - `PAPERCLIP_PAGE_AWS_ACCESS_KEY_ID` and `PAPERCLIP_PAGE_AWS_SECRET_ACCESS_KEY`23    with the page-uploader credentials from Paperclip Secrets24- Optional environment variables:25  - `PAPERCLIP_PAGE_DEFAULT_PREFIX`26  - `PAPERCLIP_PAGE_AWS_PROFILE` (alternative to the namespaced key pair)27  - `PAPERCLIP_PAGE_AWS_SESSION_TOKEN` (only together with the namespaced key28    pair)29 30Do not bind the page-uploader credentials as global `AWS_ACCESS_KEY_ID` /31`AWS_SECRET_ACCESS_KEY`: static env keys take precedence over `AWS_PROFILE` in32every AWS SDK, so global names silently replace the host identity for every33process in the agent run. The namespaced variables scope the uploader identity34to this helper only. The ambient credential chain still works as a fallback35when none of the `PAPERCLIP_PAGE_AWS_*` credential variables are set.36 37## Workflow38 391. Inspect the source directory and confirm it is public static content only.402. Run `scripts/publish.sh <dir> --dry-run` to validate local structure and see41   the resolved URL/prefix.423. Choose a slug:43   - Use `--slug <slug>` when the user gave a stable URL path.44   - Omit `--slug` to derive one from the source directory name.454. Publish:46 47```bash48.agents/skills/paperclip-page/scripts/publish.sh ./site --slug my-page49```50 515. Return the printed public URL and S3 prefix to the issue/user.52 53## Update Workflow54 55Updates are additive overwrites only. The helper never deletes remote objects.56 57```bash58.agents/skills/paperclip-page/scripts/publish.sh ./site --slug my-page --update59```60 61When the target prefix already exists, `--update` requires local ownership proof62from `./site/.paperclip-page/state.json` generated by an earlier publish from63that same source directory. Without that state, create a new slug instead of64overwriting another page.65 66## Safety Rules67 68- Publish public content only. Do not publish secrets, customer data, private69  company material, credentials, or internal logs.70- Never print AWS secret values.71- Never change bucket policy, IAM, DNS, CloudFront, or ACM settings from this72  skill. Setup belongs to an operator runbook, not the publish helper.73- Never upload outside the configured bucket and prefix.74- Never use `aws s3 sync --delete` or require `s3:DeleteObject` in v1.75- The helper forces `--no-follow-symlinks` and fails if any source symlink is76  present.77- The helper rejects hidden files and dot-segment paths except its own78  `.paperclip-page/state.json`.79- Slugs and prefix segments must use lowercase ASCII letters, digits, and80  hyphens only.81- Keep site-wide root objects such as `404.html` operator-managed; publishes82  always target `<slug>/...` or `<default-prefix>/<slug>/...`.83 84## Troubleshooting85 86- `Slug already exists`: choose a different slug or use `--update` from the87  original source directory containing `.paperclip-page/state.json`.88- `Missing index.html`: build the static site first or point the helper at the89  directory that contains the root HTML file.90- `Found symlink`: replace symlinks with real files before publishing.91- `AccessDenied`: confirm the uploader IAM policy allows `ListBucket`,92  `GetObject`, and `PutObject` for the configured bucket/prefix, and that the93  agent received the Paperclip Secrets.94- Public URL verification failed: check CloudFront deployment/DNS, object95  existence, and that the distribution uses HTTPS with the private S3 REST96  origin.97 98See `README.md` next to this skill for operator setup, AWS policy examples,99credential rotation, and install/attach commands.100