docs: add usage-telemetry and rendered-pages reference pages

[markmhendrickson]

Summary

• /usage-telemetry — new reference page for the usage_digest entity type: required fields (schema_version, period_start, period_end, reporter_channel), optional fields including aauth_sub (intentionally optional so keyless guests can submit without an AAuth keypair), operation_counts, error_rate, error_counts, entity_type_usage, tool_usage, compliance_signals, friction_notes, effectiveness_signal, notes, and redaction_salt; AAuth-grant vs keyless-guest submission; composite-key idempotency (reporter_channel+period_start+period_end); time-series retrieval via sort_by: "snapshot.period_end"; server-side PII redaction backstop on free-text fields.
• /rendered-pages — new reference page for publish_rendered_page: rendered_page entity fields (title, html_body, custom_css, meta_description), guest access token minting, the /entities/<id>/html?access_token=<token> URL shape, per-call token freshness (raw tokens not stored in recoverable form), inline-create with idempotency key, and how correct updates a live page without invalidating its share URL.
• Both pages close gaps surfaced by a partnership-hub doc-link audit (no partner named; see issue docs: add usage-telemetry and rendered-pages reference pages #1832).

What changed

Each page is a triplet: .mdx (React/MDX with footer), .md (markdown with YAML frontmatter), .meta.json. Pages registered in:

• docs/site/site_doc_manifest.yaml
• frontend/src/site/seo_metadata.ts (ROUTE_METADATA)
• frontend/src/components/MainApp.tsx (APP_ROUTES)

Generated files under docs/site/generated/ regenerated by npm run prebuild:ui and included in the commit (baseline-checked in CI). nav_order values: 116 (usage-telemetry), 117 (rendered-pages) — verified against current max of 115.

Test plan

• npm run prebuild:ui passes with ✓ MDX site page metadata validation passed.
• Manually browse /usage-telemetry and /rendered-pages on the deployed site
• Confirm JSON examples render correctly in MDX
• Confirm footer links resolve to /changelog and related pages

Closes #1832

🤖 Generated with Claude Code

[neotoma-agent]

review:pm
🤖 Pavo — Ateles swarm, pm lens panelist
APPROVE

• Scope matches issue docs: add usage-telemetry and rendered-pages reference pages #1832 (two new reference pages for usage_digest and publish_rendered_page)
• No unrequested scope creep (pages + registrations only; generated audit files are rebuild artifacts)
• Acceptance criteria met (both pages complete, registered in manifest/SEO/routes, nav_order verified, prebuild validation passed)
• User-visible behavior correct (pages will appear at /usage-telemetry and /rendered-pages with proper breadcrumbs, closes partnership-hub doc-link audit gap)

**[NON-BLOCKING] Documentation: unchecked test items — test plan marks three manual browsing/rendering checks as incomplete (manually browse routes, JSON example rendering, footer link resolution). These are reasonable post-deployment checks for doc PRs. Clarify if these are expected to run in a staging environment before production or if they are deferred to a follow-up. Holding them open is fine if immediate merge to production is scheduled; mention it in the PR comment to set expectations.

---

📎 Neotoma: neotoma#1832

[neotoma-agent]

review:ux
🤖 Accipiter — Ateles swarm, ux lens panelist
COMMENT

User-facing surface & discoverability

✓ Clear, navigable paths: Both pages are properly routed (/usage-telemetry, /rendered-pages) and registered in site manifest, SEO metadata, and MainApp.tsx. Naming is self-documenting.
✓ Breadcrumb & footer links: Each page has contextual footer navigation back to /changelog and related reference pages (/auditable-change-log for telemetry, /agent-auth for rendered pages). This supports jump-to-related-topic flow.
✓ Minimal onboarding friction: No prerequisite docs required to understand the basic use case. The intro paras (what is a usage_digest, what is a rendered_page) answer the "when should I use this" question before the "how" sections.

Interaction & task completion flow

usage-telemetry page:

• Happy path is clear: (1) define your digest shape, (2) call store with the required 4-field composite identity, (3) retrieve by period_end sort. JSON example is correct and copy-pasteable.
• Optional fields are well-organized and their purposes are explicit (e.g., aauth_sub is intentionally optional for keyless-guest submission).
• Authentication choice point (AAuth grant vs keyless-guest) is flagged early with "Two paths are supported" — developer knows they have a choice before diving into details.

rendered-pages page:

• Happy path: (1) create inline or reference existing, (2) get a share URL back, (3) optional: update via correct and the URL stays live.
• The response shape is fully documented with field-by-field notes.
• Guest URL shape /entities/<id>/html?access_token=<token> is explicit — this prevents confusion about where the token goes or how to format the URL.

Error & empty states

⚠️ [NON-BLOCKING] Information architecture: Missing redirect behavior for outdated/deleted rendered_page.
If a developer shares a URL, then later calls delete_entity or the page is garbage-collected, what does a guest see at /entities/<id>/html?access_token=<token>? The page says "correcting a page keeps the share URL live," but doesn't address the deleted-entity case. This is not a blocker for ship (guests hitting a 404 is acceptable and understandable), but a future note in error-handling or lifecycle docs would clarify expectations. No action required for this PR.

✓ usage-telemetry composite identity: The spec correctly calls out that a second store with the same [reporter_channel, period_start, period_end] returns ERR_STORE_RESOLUTION_FAILED rather than silently merging — this is explicit and prevents silent data loss.

Accessibility & clarity

✓ Table formatting: Both pages use Markdown tables for field reference. Tables are screen-reader navigable and support keyboard navigation in the rendered site.
✓ Code examples are JSON not pseudocode: Real, valid JSON in the examples — developers can copy-paste and adapt rather than needing to interpret placeholder syntax.
✓ Terminology consistency: period_end appears in sort examples matching the field name in the schema. Reduces mental mapping.

Naming & discoverability from related surfaces

✓ Related entity types are named clearly: The telemetry page mentions the relationship to harness_event (per-turn) and daemon_report (per-incident) in the intro table — helps developers choose the right entity type for their use case.
✓ SEO metadata is specific: Title and description both include the entity/operation name ("Usage telemetry," "Rendered pages"), so search/sidebar filters will show these correctly.

Acceptance checklist

• Both pages are routed and registered in site manifest, SEO metadata, and MainApp.tsx
• JSON examples are complete and copy-pasteable
• Field reference tables include required vs optional status
• Authentication/access choices are clearly documented (AAuth grant vs keyless-guest; guest access tokens)
• Footer navigation links to related reference pages
• URL shapes are explicit (composite identity for telemetry, guest URL format for rendered pages)
• No structural friction preventing a developer from finding the surface or understanding the happy path

Verdict

This is a straightforward reference-page addition with no discoverability gaps or interaction friction. Happy-path flows are explicit, examples are real, and naming is clear. The one minor note about deleted-entity behavior for rendered pages is a future clarification, not a blocker.

SIGNED_OFF — Ready to merge from UX lens.

---

📎 Neotoma: markmhendrickson/neotoma#1833

[neotoma-agent]

review:qa
🤖 Phoenicurus — Ateles swarm, qa lens panelist

APPROVE

Summary

This PR adds reference documentation pages for two existing, pre-shipped features: the usage_digest entity type and publish_rendered_page MCP tool. The changes are purely documentation and configuration (route registration, SEO metadata). No new functional logic or agent-facing surfaces are introduced.

Functional Surface

The PR modifies only:

• Documentation pages (.md, .mdx, generated files)
• Route configuration in MainApp.tsx (registering two new reference doc paths)
• SEO metadata in seo_metadata.ts (breadcrumb and page title/description for search engines)

These are non-functional changes — they expose existing, already-tested features through documentation, not new behavior.

Test Coverage Assessment

The underlying features have pre-existing test coverage:

• usage_digest entity type: Covered by unit tests

  • tests/unit/usage_digest_schema.test.ts — Validates schema registration, field types, canonical identity, temporal events, reducer merge policies
  • tests/unit/usage_digest_redaction.test.ts — Validates server-side PII redaction on ingest (friction_notes, notes fields, salt correlation)

• publish_rendered_page MCP tool: Dispatchable (confirmed via mcp_tool_dispatch_coverage.test.ts guard), advertised in src/tool_definitions.ts, routed in src/server.ts

No new branches, endpoints, or agent-observable behavior introduced in this PR.

Verdict

No functional surface — no eval required. This is a pure documentation addition. The referenced features (usage_digest, publish_rendered_page) are pre-shipped and already carry appropriate test coverage. The route and metadata additions are configuration only and carry no risk of regression.

[neotoma-agent]

review:content
🤖 Corvus — Ateles swarm, content lens panelist
COMMENT

Content review

Both reference pages are shippable. They dogfood the features directly (JSON examples for usage_digest submission and retrieval, full publish_rendered_page workflow with token lifecycle), maintain builder-to-builder voice (no marketing filler), and prioritize specificity over abstraction (actual PII patterns, composite-key idempotency rules, the intentional optionality of aauth_sub).

Strengths

• Directly actionable. The JSON examples are complete; a builder reading these can implement usage_digest submission or page publishing without backfilling context.
• Technical honesty. No superlatives ("powerful sharing," "seamless observability"). Instead: "advisory-only conformance checks," "tokens not stored in recoverable form," explicit design rationale (why aauth_sub is optional).
• Specificity. Redaction section names actual PII patterns (emails, bearer tokens, filesystem paths, UUIDs, phone numbers). Token mechanics are precise (hash persisted, raw token returned once, each call mints fresh).
• Integration voice. Direct, builder-to-builder, no engagement bait.

Forward-looking work (not blocking)

These pages are reference-focused. A follow-on opportunity: a dogfooding narrative that ties both features together and positions them relative to the observability / partnership story. (The features themselves are here and shipable; the story of why they matter together is a separate content piece. I will file a task for this.)

The pages unlock downstream use of publish_rendered_page for build-in-public reports and agent-generated summaries, which is a natural fit for Corvus content pipeline.

📎 Neotoma: Issue #1832

[neotoma-agent]

🤖 Vanellus — Ateles swarm, PR steward
APPROVE

Aggregated Review Verdict

Per-Lens Roll-up

[PM — Pavo] APPROVE ✓

• Scope matches issue docs: add usage-telemetry and rendered-pages reference pages #1832 (two new reference pages, no creep)
• Acceptance criteria met, pre-build validation passed
• [NON-BLOCKING] Unchecked manual test items (post-deployment verification acceptable)

[UX — Accipiter] SIGNED_OFF ✓

• Discoverable routes, clear navigation, no friction in happy paths
• JSON examples complete and copy-pasteable
• Field reference tables include required/optional status
• [NON-BLOCKING] Future clarification: deleted rendered_page URL behavior (acceptable as 404)

[QA — Phoenicurus] APPROVE ✓

• Pure documentation addition, no new functional logic
• Underlying features (usage_digest, publish_rendered_page) pre-shipped and well-tested
• No eval required, zero regression risk

[Content — Corvus] COMMENT ✓

• Shippable reference pages, builder-to-builder voice, no marketing filler
• JSON examples directly actionable, technical honesty
• Dogfoods both features with complete workflows and field-by-field documentation
• Forward-looking note: dogfooding narrative tying both features together (future content opportunity, not blocking)

Blocking Findings

None. No [BLOCKING] items from any lens.

CI Status

Required: — SUCCESS ✓
Advisory: baseline FAILURE (pre-existing advisory), preview IN_PROGRESS, others SUCCESS. No blockers.

Head commit: ab38dda
All verdicts matched to current head: ✓

Gate Inheritance Check

Parent issue #1832 — retrieving gate_status…

Merge Recommendation

All lenses clear. Ready for merge. Gate inheritance check in progress; will file checkpoint_brief if any pre-impl gates are pending. Operator approval required per autonomy guardrail.

---

📎 Neotoma: neotoma#1832 · neotoma#1833

[github-actions]

Docs preview

Preview URL: https://dev.neotoma.io/pr-1833/

Built from 37f54471ee81c69b2e3958a574c761e8fd1d8ce5. The preview is a static export — manifest-driven category ordering is not applied, but all doc content is rendered.