0 Fork 0

mirror of https://github.com/paperclipai/paperclip-docs.git synced 2026-11-09 04:09:33 -10:00

Files

T

Aron PrinsandClaude Opus 5 325c9eb819 seo: hand-write titles and descriptions for all 192 pages (#115 )

## 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]>

2026-08-25 22:51:42 +02:00

5.4 KiB

Raw Permalink Blame History

paperclip_version: v2026.609.0 seo_title: CLI Activity Commands seo_description: Read the company audit trail from the terminal: a chronological record of who did what to which entity, for monitoring and for debugging.

Activity Commands

The activity log is the company's audit trail: a chronological record of who did what to which entity. Reach for these commands when you are monitoring a running company, reconstructing what an agent did, or wiring an external system into the same record the Paperclip UI shows. It is exactly the trail you see in the UI's activity feed, available from the terminal for scripting, export, or headless monitoring.

activity list and activity issue are read-only. activity create is the one mutating command here, and you will rarely need it — the server already writes activity entries automatically as a side effect of normal work (issue updates, document locks, recovery resolutions). Use activity create only when you have an external event that genuinely belongs in the company's trail.

All three subcommands accept the common client options (--api-base, --api-key, --context, --profile, --data-dir, --json). activity list and activity create are company-scoped and require --company-id; activity issue resolves the company from the issue itself.

Tip: Add --json whenever you are scripting against these commands or piping the output into another tool. Without it, list prints one compact inline record per line for fast human scanning.

activity list

List the activity log entries for a company.

paperclipai activity list --company-id <company-id>
paperclipai activity list --company-id <company-id> --agent-id <agent-id>
paperclipai activity list --company-id <company-id> --entity-type issue --entity-id <issue-id>

Flag	Use
`-C, --company-id <id>`	Required. The company whose activity log you want.
`--agent-id <id>`	Filter to entries attributed to a single agent.
`--entity-type <type>`	Filter to one entity type, such as `issue`.
`--entity-id <id>`	Filter to one specific entity by id.

The filters combine: pass --entity-type issue --entity-id <issue-id> to scope the log to a single issue, or add --agent-id on top to see only what one agent did to it.

Each entry in the default (non-JSON) output is a single inline record exposing the fields you most often pivot on:

Field	Meaning
`id`	The activity entry's own id.
`action`	What happened, such as `issue.updated` or `issue.document_locked`.
`actorType`	Who acted — for example an agent, a user, or the system.
`actorId`	The id of the actor.
`entityType`	The kind of object the action touched.
`entityId`	The id of the object the action touched.
`createdAt`	When the entry was recorded.

When there are no matching entries, the command prints an empty result rather than failing. Use --json to get the full entry objects, including any payload the server stored.

activity create

Create an activity log entry on a company. The body is supplied as a raw JSON string that the server validates as a CreateActivity payload.

paperclipai activity create --company-id <company-id> \
  --payload-json '{"action":"deploy.completed","entityType":"project","entityId":"<project-id>"}'

Flag	Use
`-C, --company-id <id>`	Required. The company to record the entry against.
`--payload-json <json>`	Required. A JSON string describing the activity entry.

The CLI parses --payload-json with JSON.parse before sending it, so it must be syntactically valid JSON — wrap it in single quotes in your shell so inner double quotes survive. The server is the authority on which fields a CreateActivity payload accepts; an invalid shape comes back as a request error, which the CLI surfaces directly.

Note: You almost never need this command for normal operations. Paperclip writes activity entries on its own whenever issues, documents, and recovery actions change. Reserve activity create for stitching an external event — a deploy, an incident, a manual milestone — into the same audit trail.

activity issue

List the activity for a single issue, identified by its id or human identifier (such as PAP-39).

paperclipai activity issue <issue-id>
paperclipai activity issue PAP-39 --json

This command takes the issue as a positional argument and resolves the rest of its context (including the company) from your selected profile and the issue itself, so it does not require --company-id. It is the fastest way to answer "what has happened to this one task?" without filtering the whole company log.

activity issue <id> and activity list --company-id <id> --entity-type issue --entity-id <id> overlap, but reach for activity issue when you already have an issue identifier in hand — it is shorter and it accepts the human PAP-39 form directly.

5.4 KiB Raw Permalink Blame History