[promptless]

Proposed changes

Replaces the deprecated docmeta setup with the manni CLI (@hawkeyexl/manni 4.8.1, manni meta validate). Docs frontmatter is now validated against the open and strict versions of six manni vocabularies: core, stewardship (1.1.0), audience, lifecycle, structure, and ai-context. Values are filled on all 131 pages in src/content/docs. The vocabulary is named audience, not audiences. audiences is one of its fields.

Tooling

• docmeta.config.yaml is replaced by manni.config.yaml. It sets defaults: false, so it drops google:okf:0.1 and the other manni defaults, and runs each requested vocabulary followed by its -strict overlay. Starlight frontmatter is checked by manni's built-in astro:starlight:0.41 schema, so the hand-authored schemas/starlight-frontmatter.schema.json mirror is removed.
• type comes from manni's built-in Good Docs Project schema, tgdp:templates:1.1. It requires a non-empty type and recommends the 25 TGDP template slugs without enforcing them; the tgdp:templates-strict:1.1 overlay is not used. Pages moved from landing/guide/reference to concept (18), how-to (41), reference (61), installation-guide (6), quickstart (2), troubleshooting (2), glossary (1), and contact-support (1). Each changed page lists /type in its meta-provenance entry for review. The tags lists still carry the old type words.
• There is no custom schema, and the schemas/ directory is gone. manni:core:1.0.0 requires title and description and checks the form of id. No schema requires id, but manni meta validate still fails without it (see below). Nothing checks tags.
• .github/workflows/docmeta.yml is renamed to manni.yml. The workflow checks out the PR head with full history, because manni compares derived stamps against git.
• lint:frontmatter, AGENTS.md, and the ADR index are updated. The new ADR 0005 records the decision and supersedes Starport ADR 0006, plus part of ADR 0004.

Where values go. manni marks each field as page or external, and this PR follows those marks:

• Page frontmatter holds what readers and agents act on: id, keywords, language, audiences, intent, lifecycle, last-updated, applies-to, concepts, prerequisites / next-steps / related-pages (by page id), risks, and sample-questions.
• docs.metadata.yaml holds maintainer metadata, keyed by page id: owner, created, personas, journeys, visibility, source-of-truth (where a page documents a specific repo or file), and meta-provenance.
• Stamped from evidence. created, last-updated, and owner come from git history and CODEOWNERS through manni meta derive. CI fails if a stamp goes stale, so after a change to a page's body, run npx manni meta derive and commit the result.
• Review trail. Audiences, personas, and journeys use the content-strategy ids. Every page's machine-proposed values are listed in its meta-provenance entry. Delete a page's entry once you've reviewed it.

Intentionally left unset

• authors, reviewed-by, last-reviewed, and provenance change at merge time, so they'd need a derive run on main to stay accurate.
• stakeholders, review-interval, and verified-against are team decisions that no evidence records.

Checklist

• Instructions and examples match the current product behavior.
• Links and image references are valid.
• Changed pages render correctly.

Verification:

• npx manni meta validate: 132 files passed, 0 errors, no location warnings.
• npx manni meta derive --check: clean.
• npm run lint:md: clean.
• npm run build: succeeds, and page routes are unchanged.
• npm run test:smoke: 28 of 28 tests pass.
• Vale: no new findings on the docs pages. Only frontmatter changed in those files.
• After the schema cleanup: npx manni meta validate passes 132 of 132 files. A page with no type fails tgdp:templates:1.1. A misspelled type such as how-too now passes. Deleting id from an existing page still fails, because its docs.metadata.yaml entry no longer matches a page. A new page without id fails derived:stale for owner and created, because derive has no docs.metadata.yaml entry to stamp.

After main was merged into this branch (bringing in #1047), npx manni meta derive re-stamped last-updated on the four governance pages whose bodies #1047 changed: supported-agents, trace-object-and-sources, how-it-works, and key-concepts.

After the next main merge (bringing in #1103 and #1125), npx manni meta derive re-stamped last-updated on remediate-findings and pig-cli-reference, whose bodies those PRs changed. This fixes the stale-stamp failure in the validate check. Validation now covers 132 files, including the new capture-cloud-agent-traces page.

Review feedback (Manny)

• Applied: "Don't define type in the custom frontmatter schema. Use the built-in tgdp schema for the type overlay." type is gone from the custom schema, and manni.config.yaml stacks tgdp:templates:1.1 and tgdp:templates-strict:1.1 before the extension seam. Because the strict overlay doesn't accept landing or guide, every page's type was moved to a TGDP slug.
• Answered: "Why do we need this file?" The manni vocabularies already cover title, description, and the form of id and type, so the schema now drops those rules. It stays for the two rules nothing else enforces: requiring id, and the tags check. (Superseded by the next round.)
• Applied: "Drop "tags" from here and remove this custom schema." schemas/custom-frontmatter.schema.json is deleted, along with its tags check and id requirement. Pages keep their tags lists, but nothing validates them. A new page without id now passes CI, and its maintainer metadata in docs.metadata.yaml then has nothing to join on. AGENTS.md tells authors to add id anyway.
• Applied: "Drop the tgdp strict schema, too." tgdp:templates-strict:1.1 is gone from manni.config.yaml. type is still required, but any non-empty string passes. All pages already use TGDP slugs.
• Applied: "Drop this schema in favor of manni's built-in starlight schema." schemas/starlight-frontmatter.schema.json is deleted, and the config uses astro:starlight:0.41, which matches the repo's Starlight 0.41.3. The manni workflow no longer runs on schemas/** changes. ADR 0005 and AGENTS.md describe the new schema set.
• Applied: "I believe ci does require id with the new strict schemas in place." Confirmed with manni 4.8.1 on Node 24. No schema requires id, but manni meta validate fails without it. A new page without id fails derived:stale for owner and created, and an existing page that drops its id leaves an orphaned docs.metadata.yaml entry. AGENTS.md and the ADR 0005 tradeoff now say CI fails without id.
• Answered, no change: "Would it make more sense to run manni check to catch everything that's been configured instead of just metadata?" manni status reports meta as the only check set up, so manni check would currently run the same validation. On this branch, though, manni check exits 2: its cite check step can't run and reports all 132 docs.metadata.yaml entries as orphans, even though manni meta validate passes 132 of 132 files. CI and lint:frontmatter keep manni meta validate until manni check runs clean here.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
promptless-docs	Ready	Preview	Oct 19, 2026 8:06pm UTC

[promptless]

I noticed that some CI checks failed for this PR. I'm investigating whether the failures are caused by this suggestion. If they're unrelated or pre-existing, I'll leave this suggestion unchanged and create a separate suggestion if a standalone docs fix is needed.

[promptless]

I noticed that some CI checks failed for this PR. I'm investigating whether the failures are caused by this suggestion. If they're unrelated or pre-existing, I'll leave this suggestion unchanged and create a separate suggestion if a standalone docs fix is needed.

[hawkeyexl]

Don't define type in the custom frontmatter schema. Instead, use the built-in tgdp schema for the type overlay.

[hawkeyexl]

@Promptless why do we need this file? Don't the manni vocabularies handle these fields already?

[promptless]

You're asking whether the custom frontmatter schema file is still needed now that the manni vocabularies cover these fields. I'm checking that against the vocabularies and will reply here with the answer and any change to the suggestion.

[promptless]

So far, the manni core vocabulary already requires title and description, so the custom schema's remaining jobs look like requiring id and checking tags; I'm now moving type to the built-in tgdp schema, which means remapping the type values on 132 pages to TGDP names.

[promptless]

Mostly, yes. manni:core:1.0.0 already requires title and description, and it checks the format of id and type. I've removed those rules from the custom schema. The built-in tgdp:templates:1.1 schema and its tgdp:templates-strict:1.1 overlay now check type (see the other thread).

The file stays for two rules that nothing else in the stack enforces:

• It makes id required. Core defines id but doesn't require it, and docs.metadata.yaml looks up each page's maintainer metadata by id. A page without an id would silently get no metadata.
• It checks the format of tags, which no manni vocabulary defines.

If you're happy to drop the tags check and move the id requirement elsewhere, the file can go entirely.

One correction to my earlier update: 71 pages got a new type value, not 132. All 132 pages pass manni meta validate.

Docs PR: #1165

[hawkeyexl]

Drop "tags" from here and remove this custom schema.

[hawkeyexl]

Drop the tgdp strict schema, too.

[promptless]

You want to remove the custom frontmatter schema, including its tags check, and drop the tgdp strict overlay. I'm making both changes now and will reply here with what changed and what the remaining schemas no longer check.

[promptless]

Done: I deleted the custom frontmatter schema and removed the tgdp:templates-strict:1.1 overlay from manni.config.yaml.

CI no longer checks three things:

• tags: Pages keep their tags lists, but nothing validates them.
• type: tgdp:templates:1.1 still requires a non-empty type, but the 25 Good Docs Project page types are now only recommended. A typo such as type: how-too passes CI. Every current page uses a valid type.
• id on new pages: A new page without an id passes CI, and its docs.metadata.yaml entry then has no id to attach to. Removing id from an existing page still fails, because manni reports the leftover docs.metadata.yaml entry as an error. AGENTS.md now tells authors to always add id.

All 132 pages pass manni meta validate. I re-requested your review.

Review: https://app.gopromptless.ai/suggestions/8d5c29e5-1932-495d-9f09-0b918851c257
Docs PR: #1165

[promptless]

In reply to this discussion

Done. type is out of the custom frontmatter schema, and manni.config.yaml now checks it with the built-in tgdp:templates:1.1 schema and the tgdp:templates-strict:1.1 overlay.

The strict overlay rejects landing and guide, so I gave 71 pages a TGDP type:

• Former landing pages are now concept.
• Former guides are now how-to, concept, quickstart, installation-guide, or troubleshooting.
• Three reference pages became glossary, contact-support, and troubleshooting, one each.

Each changed page lists /type in its meta-provenance entry, so you can check each new value. I picked these types, so change any that don't fit. All 132 pages pass manni meta validate, and a page with type: guide or no type now fails. The tags lists still contain guide, landing, and reference, because this comment didn't ask for that change.

Docs PR: #1165

[hawkeyexl]

Drop "tags" from here and remove this custom schema.

[hawkeyexl]

Drop the tgdp strict schema, too.

[hawkeyexl]

Drop this schema in favor of manni's built-in starlight schema.

[promptless]

You want to replace this Starlight schema with the one built into manni. I'm making that change now and will reply here when it's done.

[promptless]

Done: I deleted schemas/starlight-frontmatter.schema.json, and manni.config.yaml now uses manni's built-in astro:starlight:0.41 schema, which matches the repo's Starlight 0.41.3.

The built-in schema requires title and checks the other Starlight fields when a page sets them. With both schema files deleted, the schemas/ directory is gone, so I also removed schemas/** from the paths that trigger the manni workflow.

Review: https://app.gopromptless.ai/suggestions/8d5c29e5-1932-495d-9f09-0b918851c257
Docs PR: #1165

[hawkeyexl]

Would it make more sense to run manni check to catch everything that's been configured instead of just metadata?

[promptless]

You are asking whether this step should run manni check, so it catches every configured check and not only metadata. I am checking what manni check covers and will reply here with the change or an answer.

[promptless]

In principle, yes. Today manni status lists meta as the only check that is set up, so manni check would run the same validation as manni meta validate. On this branch it also exits 2 under manni 4.8.1: its cite check step reports all 132 docs.metadata.yaml entries as orphans, even though manni meta validate passes all 132 files and cite is not set up. Running manni cite check alone gives the same error, which looks like a manni bug. Switching CI or lint:frontmatter to manni check would break CI now, so both still run manni meta validate. Do you want to switch now and fix cite check upstream, or keep meta validate until manni check runs clean?

[hawkeyexl]

I believe ci does require id with the new strict schemas in place.

[promptless]

You are pointing out that CI may now require id under the new strict schemas. I am checking the schemas and the CI behavior and will reply here with what I find or change.

[promptless]

Confirmed with manni 4.8.1: removing id fails meta validate, and a new page without id fails the stale check for owner and created. I am updating this line and the matching tradeoff in ADR 0005 to say CI requires id.

[promptless]

You're right. No schema requires id, but manni meta validate fails without it. A new page with no id fails derived:stale for owner and created, because those values are stored in docs.metadata.yaml under the page's id. A page that drops its id leaves its docs.metadata.yaml entry orphaned. AGENTS.md line 141, the ADR 0005 tradeoff, and the PR description now say that CI requires id and explain why.