0 Fork 0

mirror of https://github.com/paperclipai/paperclip-docs.git synced 2026-11-10 03:51:29 -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

7.2 KiB

Raw Permalink Blame History

paperclip_version, seo_title, seo_description

paperclip_version	seo_title	seo_description
v2026.609.0	CLI Goal Commands	Set, inspect, and restructure the strategic objectives that issues and projects ultimately serve — the why behind the work.

Goal Commands

Goals are the company's strategic objectives — the "why" that issues and projects ultimately serve. Reach for these commands when you want to set, inspect, restructure, or retire a company's goals from the terminal: building a goal tree, pointing a project at the goals it advances, or marking an objective as achieved. Goals are company-scoped, can nest into a hierarchy, and can be owned by an agent.

How goals fit the model

A goal sits above the day-to-day work. Projects and issues hang off goals, not the other way around:

A project is created against one or more goals — project create takes --goal-ids. The project is the vehicle that moves those goals forward. See Project Commands.
An issue can carry a goalId, and when it doesn't, the server resolves a goal in order of precedence: the issue's own goal, then the project's goal, then the company's default goal. See Issue Commands.
A goal can have a parent goal (--parent-id), which lets you model a tree — a company-level goal with team-level or quarter-level sub-goals beneath it.
A goal can have an owner agent (--owner-agent-id), the agent accountable for it.

Because goals anchor the whole hierarchy, treat them as durable. You will create them rarely, update their status as objectives progress, and delete almost never.

All goal commands accept the common client options (--data-dir, --api-base, --api-key, --context, --profile, --json). The collection commands (list, create) are company-scoped and take -C, --company-id <id>; the single-goal commands (get, update, delete) address a goal directly by its ID. See Common Options for the shared flags and the API base resolution order.

List goals

List every goal for a company.

paperclipai goal list --company-id <company-id>
paperclipai goal list --company-id <company-id> --json

Flag	Use
`-C, --company-id <id>`	Company whose goals to list. Required (resolved from context if a company is selected).

The default human output prints one line per goal showing id, status, title, level, parentId, and ownerAgentId — enough to read the tree at a glance. Use --json when you are scripting and want the full goal records.

Tip: Pipe goal list --json through jq to find the children of a goal (jq '[.[] | select(.parentId == "<goal-id>")]') or to pull out the company-level objectives (jq '[.[] | select(.level == "company")]').

Get a goal

Fetch a single goal by its ID.

paperclipai goal get <goal-id>
paperclipai goal get <goal-id> --json

This addresses the goal directly, so you do not pass --company-id. Use it to confirm a goal's current status, owner, or parent before you wire a project or issue to it.

Create a goal

Create a goal in a company.

paperclipai goal create --company-id <company-id> --title "Grow revenue 30% this year"

Flag	Use
`-C, --company-id <id>`	Company to create the goal in. Required.
`--title <title>`	The goal's title. Required.
`--description <text>`	Longer description of the objective.
`--level <level>`	The goal's level in the hierarchy (for example a company-level vs. team-level objective).
`--status <status>`	Initial status.
`--parent-id <id>`	Parent goal, to nest this goal under another.
`--owner-agent-id <id>`	Agent accountable for the goal.

--title and --company-id are the only required inputs; everything else is optional and the server applies its own defaults for level and status when you omit them. The command prints the created goal (pass --json for the raw record), so capture the returned id to use in project create --goal-ids or on an issue's goalId.

A nested example — a company objective with a team sub-goal owned by an agent:

# Top-level company goal
paperclipai goal create --company-id <company-id> \
  --title "Reach profitability" --level company

# Sub-goal that rolls up into it, owned by the growth lead
paperclipai goal create --company-id <company-id> \
  --title "Launch paid tier" \
  --parent-id <parent-goal-id> \
  --owner-agent-id <agent-id>

Note: Pass --owner-agent-id only when an agent should be accountable for the goal. Ownership is an accountability signal, not an assignment — agents pick up actual work through issues, not goals.

Update a goal

Update a goal's fields. Every field is optional; send only what you want to change.

paperclipai goal update <goal-id> --status achieved
paperclipai goal update <goal-id> --title "Grow revenue 40% this year" --description "Stretch target after Q2 beat"

Flag	Use
`--title <title>`	New title.
`--description <text\|null>`	New description, or `null` to clear it.
`--level <level>`	New level.
`--status <status>`	New status — this is how you mark a goal active, achieved, or abandoned as it progresses.
`--parent-id <id\|null>`	Re-parent the goal, or pass `null` to promote it to a top-level goal.
`--owner-agent-id <id\|null>`	Reassign the owning agent, or `null` to clear ownership.

For the nullable fields — --description, --parent-id, and --owner-agent-id — the literal value null clears the field, while any other value sets it. This is the only way to detach a goal from its parent or remove its owner without deleting the goal.

# Promote a sub-goal to the top level and hand it off
paperclipai goal update <goal-id> --parent-id null --owner-agent-id <new-owner-id>

# Clear an owner entirely
paperclipai goal update <goal-id> --owner-agent-id null

The command does not address goals by company, so you do not pass --company-id.

Delete a goal

Delete a goal. This is guarded — you must pass --yes or the command refuses.

paperclipai goal delete <goal-id> --yes

Flag	Use
`--yes`	Confirm the deletion. Without it the command errors with "Deletion requires --yes."

Deleting a goal is a structural change: projects created against it and issues that referenced its goalId lose that link, and any child goals lose their parent. Prefer updating a goal's status to "achieved" or "abandoned" over deleting it — that keeps the strategic history intact. Delete only when a goal was created in error.

Warning: goal delete requires the explicit --yes flag because removing a goal can orphan the projects and issues that pointed at it. Confirm you have nothing live hanging off the goal before you run it.

7.2 KiB Raw Permalink Blame History