Skip to content

feat: agent-readable surface for docs.affitor.com - #76

Merged
sonpiaz merged 6 commits into
mainfrom
feat/agent-readable-surface
Sep 13, 2026
Merged

feat: agent-readable surface for docs.affitor.com#76
sonpiaz merged 6 commits into
mainfrom
feat/agent-readable-surface

Conversation

@sonpiaz

@sonpiaz sonpiaz commented Sep 12, 2026

Copy link
Copy Markdown
Member

Summary

  • Shared agent markdown renderer (src/lib/agent-md.ts) with unchanged twin bodies; twins gain id/type/url/updated frontmatter.
  • Compact /llms.txt regenerated on every build (prebuild), plus /llms-full.txt, sitemap (HTML + .md twins), robots Allow blocks for AI bots, and TechArticle JSON-LD + data-page-id on docs HTML.
  • CI guard (scripts/check-agent-surface.mjs + .github/workflows/agent-surface.yml) asserts twin inventory, sitemap parity, freshness, and robots.

Routing, page URLs, content/, the blog proxy, and crawler analytics are unchanged. Based on main. Do not merge automatically — CoS review first.

Test plan

  • npm ci && npm run build && node scripts/check-agent-surface.mjs (green: 77 pages, 156 sitemap URLs, 2166 llms.txt bytes)
  • Mutation A: drop one sitemap URL → FAIL → restore → PASS
  • Mutation B: hand-edit public/llms.txt → FAIL → restore → PASS
  • Verify Vercel preview curls for /llms.txt, /llms-full.txt, /index.md, /getting-started/how-it-works.md, /sitemap.xml, /robots.txt
  • CoS independent review before merge

Made with Cursor

sonpiaz and others added 4 commits September 12, 2026 12:42
@sonpiaz
feat: share the existing agent markdown renderer
2e7f07c 
Constraint: Preserve every rendered body and existing routing.

Confidence: high
@sonpiaz
feat: publish shared agent metadata and full documentation
9f4a38f 
Constraint: Preserve source bodies, URLs, routing and integration names.

Confidence: high
@sonpiaz
feat: regenerate compact agent discovery on every build
e2b78a4 
Constraint: Keep source-derived section descriptions and all crawler access.

Confidence: high
@sonpiaz @cursoragent
feat: guard agent discovery surface in CI
80d2232 
Constraint: Assert twins, sitemap, llms freshness and robots without changing rendered bodies.

Confidence: high
Co-authored-by: Cursor <cursoragent@cursor.com>
@vercel

vercel Bot commented Sep 12, 2026 •
edited
Loading

Copy link
Copy Markdown

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

Project Deployment Actions Updated
affitor-docs Ready Ready Preview Sep 12, 2026 8:15pm UTC

Request Review

@sonpiaz @cursoragent
fix: stop agent-surface guard from re-statting updated times
b5ba0e7 
CI saw a 1ms changelog mtime drift between next build and the post-build check. Compare twin updated to the sitemap date from the same build instead.

Confidence: high
Co-authored-by: Cursor <cursoragent@cursor.com>
@sonpiaz @cursoragent
fix: use real frontmatter dates; omit docs dates
2cfc610 
Build checkout mtimes were advertising every page as modified at deploy time. Blog and changelog now use source dates; docs omit updated/lastmod/dateModified; guard rejects mtime regressions.

Confidence: high
Co-authored-by: Cursor <cursoragent@cursor.com>
@sonpiaz

sonpiaz commented Sep 12, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

CoS verification (cos-affitor)

Not an independent approval. cos-affitor wrote the brief this PR implements and supervised the build, so this is
the brief author's verification, not a review by someone independent of the work. Approval and merge are pending.
Everything below was re-measured, not copied from the build report.

Check Result
Scope 13 files, all inside the brief's allowed list; nothing under content/, no .internal/, no lessons.md
CI check (the new guard) green on 2cfc610; Vercel preview deployed
Preview /llms.txt 200 text/plain 2,166 B (was 18,239 B) · /llms-full.txt 200 · /index.md and /getting-started/how-it-works.md 200 text/markdown · /sitemap.xml 200 (was 404) · /robots.txt 200
Same source (rule 2.5) reran scripts/gen-llms.js: output byte-identical to the committed public/llms.txt
Stable ids id identical in .md frontmatter, data-page-id and JSON-LD identifier
Sitemap 77 HTML + 77 .md + 2 txt; no preview host leaking
XSS JSON-LD serialised with replace(/</g, '<')
Vendor names none in generated text; content left exactly as written

Found and fixed in review round 1: every date came from file mtime, so on Vercel all 77 pages claimed they
had just been modified (all 102 sitemap lastmod values inside 7 ms) and the freshness check could never fail.
Now blog and changelog use their real frontmatter dates and docs pages, which have none, omit the date entirely.
Verified on the preview: a blog post shows 2026-07-05 in its source, its .md and both sitemap entries.

Guard proven red by cos-affitor (separately from the builder's own proofs): planted new Date().toISOString() in place of the blog
date, rebuilt, ran scripts/check-agent-surface.mjs → exit 1 (+ '2026-09-12T20:17:44.337Z' vs - '2026-07-06').
Restored; file byte-identical to the commit.

Known debt, not in this PR: docs pages have no real modification date; git-history dates need a full clone at build.

@sonpiaz
sonpiaz merged commit 80be301 into main Sep 13, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@sonpiaz