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]>
103 lines
5.3 KiB
Markdown
103 lines
5.3 KiB
Markdown
---
|
|
paperclip_version: v2026.609.0
|
|
seo_title: CLI Asset Commands
|
|
seo_description: Push image assets into a company from the terminal — a logo, a documentation image, or any binary blob you want to reference later.
|
|
---
|
|
|
|
# Asset Commands
|
|
|
|
Use these commands when you need to push image assets into a company from the terminal — a company logo, a documentation image, or any binary blob you later want to fetch back. The CLI uploads the file to the Paperclip API as `multipart/form-data` and prints the stored asset record; `asset content` is the inverse, streaming an asset's bytes back out by id. Reach for these when you are scripting company branding or bootstrapping content without opening the UI.
|
|
|
|
All three subcommands accept the [common client options](./common-options.md) (`--data-dir`, `--api-base`, `--api-key`, `--context`, `--profile`, `--json`). The two upload commands are company-scoped and take `-C, --company-id <id>`; `asset content` works on a global asset id and is not company-scoped.
|
|
|
|
---
|
|
|
|
## Upload an image
|
|
|
|
```sh
|
|
paperclipai asset image:upload \
|
|
--company-id <company-id> \
|
|
--file ./diagram.png \
|
|
--namespace docs \
|
|
--alt "Architecture diagram" \
|
|
--title "System overview"
|
|
```
|
|
|
|
`image:upload` posts the file to `/api/companies/<company-id>/assets/images` and returns the stored asset record (an asset id you can later pass to `asset content`).
|
|
|
|
| Flag | Use |
|
|
|---|---|
|
|
| `--file <path>` | **Required.** Path to the image file on disk. The CLI reads the bytes, infers the content type from the file extension, and sends the original filename. |
|
|
| `-C, --company-id <id>` | The company that owns the asset. Required unless resolved from your selected context/profile. |
|
|
| `--namespace <value>` | Optional namespace suffix that groups the asset under a logical bucket (for example `docs`). |
|
|
| `--alt <text>` | Optional alt-text metadata stored with the asset. |
|
|
| `--title <text>` | Optional title metadata stored with the asset. |
|
|
|
|
> **Tip:** The content type is inferred from the file path, so keep a correct extension (`.png`, `.svg`, `.jpg`) on the file you upload. A misnamed file will be stored with the wrong type.
|
|
|
|
---
|
|
|
|
## Upload a logo
|
|
|
|
```sh
|
|
paperclipai asset logo:upload \
|
|
--company-id <company-id> \
|
|
--file ./logo.svg
|
|
```
|
|
|
|
`logo:upload` posts the file to `/api/companies/<company-id>/logo` and sets the company's logo. It is the same multipart upload as `image:upload`, but it does **not** accept `--namespace`, `--alt`, or `--title` — a logo is a single, well-known slot on the company, so there is no metadata to attach.
|
|
|
|
| Flag | Use |
|
|
|---|---|
|
|
| `--file <path>` | **Required.** Path to the logo file. SVG and standard raster formats both work; the content type is inferred from the extension. |
|
|
| `-C, --company-id <id>` | The company whose logo you are setting. Required unless resolved from context/profile. |
|
|
|
|
> **Note:** This replaces whatever logo the company currently has. There is no separate "remove logo" subcommand here — upload a new file to change it.
|
|
|
|
---
|
|
|
|
## Download asset content
|
|
|
|
```sh
|
|
# Write the bytes to a file
|
|
paperclipai asset content <asset-id> --out ./asset.bin
|
|
|
|
# Or stream the bytes to stdout (pipe or redirect them)
|
|
paperclipai asset content <asset-id> > ./asset.bin
|
|
```
|
|
|
|
`asset content <assetId>` fetches the raw bytes from `/api/assets/<asset-id>/content`. By default it writes those bytes straight to stdout, which lets you pipe or redirect them. Pass `--out <path>` to have the CLI write the file for you instead — in that mode it prints a small confirmation object (`{ ok, out, bytes }`) rather than the binary.
|
|
|
|
| Flag | Use |
|
|
|---|---|
|
|
| `--out <path>` | Write the downloaded content to this file instead of stdout. When set, the command prints a confirmation summary including the byte count. |
|
|
|
|
> **Warning:** Without `--out`, the command writes raw binary to stdout. Always redirect or pipe it (`> file` or `| tool`) — printing binary directly into a terminal will garble your session. The `--json` flag has no effect in stdout-streaming mode; it only shapes the confirmation object emitted when you use `--out`.
|
|
|
|
---
|
|
|
|
## Scripting
|
|
|
|
Both uploads honor `--json`, so you can capture the returned asset id and feed it back into a download or another command:
|
|
|
|
```sh
|
|
ASSET_ID=$(paperclipai asset image:upload \
|
|
--company-id <company-id> \
|
|
--file ./diagram.png \
|
|
--json | jq -r '.id')
|
|
|
|
paperclipai asset content "$ASSET_ID" --out ./roundtrip.png
|
|
```
|
|
|
|
API base resolution follows the standard order (`--api-base`, then `PAPERCLIP_API_URL`, then your selected context profile, then the local config port, then `http://localhost:3100`). If a connection fails, the error names the URL it tried so you can confirm you are pointed at the right instance — see [common options](./common-options.md) and [output and scripting](./output-and-scripting.md) for the full conventions.
|
|
|
|
---
|
|
|
|
## See also
|
|
|
|
- [Common Options](./common-options.md) — the flags every client command shares, including `--company-id` and API base resolution
|
|
- [Output and Scripting](./output-and-scripting.md) — how `--json` shapes results and how to consume them
|
|
- [Skills Commands](./skills.md) — managing a company's skill library, another company-scoped file workflow
|
|
- [Adapter Commands](./adapter.md) — configuring the runtime adapters that execute agent work
|
|
- [Company Commands](./company.md) — inspecting and exporting the company that owns these assets
|