mirror of
https://github.com/paperclipai/paperclip-docs.git
synced 2026-11-09 12:21:27 -10:00
Aron PrinsandClaude Opus 5
325c9eb819
## Why
The build derived `<title>` from the **sidebar label** and the
description from the **first paragraph clipped to 220 characters**. Both
are the wrong source. A sidebar label is written for a 240px-wide nav
that supplies its own context; a search result has none.
On production that produced:
- **7 pages titled "Overview"**, and 32 pages sharing a title with
another page
- **109 of 193 descriptions cut off mid-word**, and 174 over 160
characters (where Google truncates)
```
/guides/welcome/key-concepts/
BEFORE (220): ...and if you misunderstand them early, the product wi
```
Near-identical titles are the weak-differentiation signal behind
"crawled — currently not indexed", which is the exact symptom on this
property.
## What changed
`seo_title` and `seo_description` frontmatter on **every one of the 192
pages**, written by hand against each page's real content and optimised
for the click — lead with what the reader can do, name the concrete
things covered, no keyword stuffing, no repeating the title.
| | Before | After |
|---|---|---|
| Duplicate titles | 32 pages | **0** |
| Duplicate descriptions | — | **0** |
| Descriptions cut mid-word | 109 | **0** |
| Descriptions over 160 chars | 174 | **0** |
| Title length (incl. suffix) | up to "Overview" | **26–60** |
| Description length | 31–240 | **122–158** |
**No prose was rewritten.** I measured content overlap between the
colliding pairs first — only 17–23%, so these were always distinct pages
wearing the same label, not duplicate content. The `docs/` diff is **564
insertions, zero deletions**.
### Examples
```
BEFORE — all seven identical: "Overview | Paperclip Docs"
AFTER: "Adapters Overview" "API Overview" "CLI Overview"
"Deployment Overview" "Bundled Skills" "Optional Skills"
"Experimental Features"
BEFORE — both identical: "Issues | Paperclip Docs"
AFTER: "Issues: Creating and Tracking Work" /guides/day-to-day/issues/
"Issues API" /reference/api/issues/
```
```
/guides/getting-started/five-minute-path/
BEFORE (220): The shortest route from a running Paperclip instance to an agent that has
just completed work for you. After Paperclip is installed, the path takes
about 5 minutes: create a company, hire a CEO agent, approve its first s
AFTER (131): Install Paperclip, create a company, hire a CEO agent, and approve its
first strategy — a working AI company in about five minutes.
```
## Plumbing
- **`site/build-release.mjs`** prefers the authored fields; the derived
path stays only as a fallback the CI gate prevents ever reaching.
`<title>`, `<meta name="description">`, and the `TechArticle` JSON-LD
all read from the same source.
- **`site/app.js`** uses the same fields, so a client-side transition
cannot leave a different title on screen than the crawler was served.
Verified in-browser: navigating `/guides/day-to-day/issues/` →
`/reference/api/issues/` swaps to exactly the server-rendered values, no
JS errors.
- **`scripts/verify-seo-metadata.mjs`** (new) enforces presence,
uniqueness, length, complete-sentence endings, and the
frontmatter-safety rules. Wired into `docs:test` and CI as its own step.
I negative-tested the gate rather than assuming it works — it correctly
fails on a duplicate title, a mid-word description, and a missing field,
and passes again once restored.
## Automating it going forward
`skills/sync-docs/SKILL.md` now:
- gains an **"Authored SEO metadata"** section: why the fields exist,
the enforced rules as a table, and how to actually write them (title
names the subject not the nav position; description writes for the
click; never generate mechanically from the first paragraph — *that is
the fallback the gate exists to prevent*).
- requires both fields in the **page-authoring instruction** given to
every subagent, with guidance on when to update an existing description
versus leave it.
- runs `docs:test:seo-metadata` and `docs:test:crawlable-links` as
**fail-loud gates in Phase 7** before commit.
- documents all six build gates in the files/gates section.
So once this lands, a new page cannot ship without hand-written
metadata, and a title collision cannot reach production.
## Verified
All six verifiers pass:
```
Static route verification passed
Asset fingerprint verification passed
Hierarchical Skills nav verification passed
Skill source block verification passed (11 skill pages, 1 control page)
Crawlable-link contract passed: 40886 internal links across 194 pages resolve in one hop
Authored-SEO contract passed: 192 pages carry a unique, hand-written seo_title and seo_description
```
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5 (1M context) <[email protected]>
146 lines
4.0 KiB
Markdown
146 lines
4.0 KiB
Markdown
---
|
|
seo_title: Deployment Modes
|
|
seo_description: Two runtime modes and one exposure choice. The mode sets how the board operator authenticates; the exposure sets who can reach the instance.
|
|
---
|
|
|
|
# Deployment Modes
|
|
|
|
Paperclip has two runtime modes and one exposure choice. The mode determines how the board operator authenticates; the exposure choice determines whether the instance stays private or is reachable publicly.
|
|
|
|
Use this page when you are deciding how to run the instance, migrating an existing install, or checking what `paperclipai doctor` expects.
|
|
|
|
---
|
|
|
|
## Mode Summary
|
|
|
|
| Mode | Exposure | Authentication | Typical use |
|
|
|---|---|---|---|
|
|
| `local_trusted` | Local only | No login required | Personal installs, development, demos |
|
|
| `authenticated` + `private` | Private network | Login required | Tailscale, VPN, LAN |
|
|
| `authenticated` + `public` | Internet-facing | Login required | Hosted production |
|
|
|
|
> **Note:** `local_trusted` is the default. If you never change anything, Paperclip behaves like a trusted local operator tool.
|
|
|
|
---
|
|
|
|
## `local_trusted`
|
|
|
|
This is the simplest operating mode.
|
|
|
|
- The board operator is implicitly trusted
|
|
- The instance is intended for a single local user
|
|
- Login friction is removed
|
|
- The host typically stays bound to `localhost`
|
|
|
|
Choose this when:
|
|
|
|
- you are installing Paperclip for yourself
|
|
- you want the fastest path to a working instance
|
|
- you are not exposing the app to other users or devices
|
|
|
|
Do not choose this when:
|
|
|
|
- other people need to log in
|
|
- the instance is reachable over a network
|
|
- you need a durable deployed setup
|
|
|
|
Set it during onboarding:
|
|
|
|
```sh
|
|
pnpm paperclipai onboard
|
|
```
|
|
|
|
---
|
|
|
|
## `authenticated`
|
|
|
|
This mode requires login for human access.
|
|
|
|
It is the right choice when the board is not the only person who may open the app, or when the instance is exposed beyond a single trusted local machine.
|
|
|
|
`authenticated` has two exposure policies:
|
|
|
|
### `authenticated` + `private`
|
|
|
|
Use this for Tailscale, VPN, or LAN access.
|
|
|
|
- Better Auth handles login
|
|
- The server binds to all interfaces
|
|
- The base URL can be inferred from the current network context
|
|
- Private hostnames may need to be allowlisted
|
|
|
|
Choose this when the instance should be reachable from other trusted devices but not exposed publicly.
|
|
|
|
Example onboarding path:
|
|
|
|
```sh
|
|
pnpm paperclipai onboard
|
|
```
|
|
|
|
Then choose the authenticated private option.
|
|
|
|
If you need to allow a custom hostname, add it explicitly:
|
|
|
|
```sh
|
|
pnpm paperclipai allowed-hostname my-machine.tailnet.ts.net
|
|
```
|
|
|
|
See [Tailscale Private Access](./tailscale-private-access.md) for the private-network workflow.
|
|
|
|
### `authenticated` + `public`
|
|
|
|
Use this for internet-facing deployments.
|
|
|
|
- Login is required
|
|
- The public base URL must be explicit
|
|
- `doctor` runs stricter checks
|
|
- The deployment should be treated as a real hosted service
|
|
|
|
Choose this when you are publishing Paperclip on the public internet.
|
|
|
|
Example onboarding path:
|
|
|
|
```sh
|
|
pnpm paperclipai onboard
|
|
```
|
|
|
|
Then choose the authenticated public option.
|
|
|
|
---
|
|
|
|
## Migrating Modes
|
|
|
|
If you start in `local_trusted` and later move to an authenticated deployment, Paperclip emits a one-time board-claim URL at startup.
|
|
|
|
The claim link looks like this:
|
|
|
|
```txt
|
|
/board-claim/<token>?code=<code>
|
|
```
|
|
|
|
A signed-in user visits the link to claim board ownership. That flow:
|
|
|
|
- promotes the current user to instance admin
|
|
- demotes the auto-created local board admin
|
|
- keeps the claiming user in active company membership
|
|
|
|
> **Warning:** Treat the claim URL as sensitive. It is intended for a one-time ownership transfer, not for general sharing.
|
|
|
|
---
|
|
|
|
## Changing The Mode
|
|
|
|
The canonical way to change mode after setup is through configuration:
|
|
|
|
```sh
|
|
pnpm paperclipai configure --section server
|
|
```
|
|
|
|
You can also override the mode for a run with an environment variable:
|
|
|
|
```sh
|
|
PAPERCLIP_DEPLOYMENT_MODE=authenticated pnpm paperclipai run
|
|
```
|
|
|
|
> **Tip:** If `paperclipai doctor` is complaining about host or auth settings, check the deployment mode first. A lot of apparent configuration errors are really mode mismatches.
|