feat(site): build the coding agent tips publication

why:
- make the field guide inspectable as a focused publication instead of a claude-only repository archive
- preserve markdown as canonical content while adding starlight navigation, search, and accessible responsive structure

evidence:
- implemented the approved homepage and guide concepts with the locked public identity, exact color system, self-hosted fonts, and evidence rail
- migrated active pages to validated frontmatter and canonical public routes

verified:
- bun run check
- bun run build
- desktop and mobile browser review at 375, 768, 1024, and 1440 pixels
- exact homepage h1 appears once and tested routes have no horizontal overflow

intentionally unverified:
- production hosting, custom-domain behavior, and github pages remain gated on the public cutover

Author: Codex

.gitignore

@@ -9,6 +9,10 @@ docs/upstream-watcher-design.md
 !.claude/commands/
 !.claude/rules/
 node_modules/
+.astro/
+dist/
+playwright-report/
+test-results/
 .DS_Store
 *.pyc
 __pycache__/

astro.config.mjs

@@ -0,0 +1,60 @@
+import sitemap from '@astrojs/sitemap';
+import starlight from '@astrojs/starlight';
+import icon from 'astro-icon';
+import { defineConfig } from 'astro/config';
+
+const repository = 'https://github.com/anipotts/coding-agent-tips';
+
+export default defineConfig({
+  site: 'https://agents.anipotts.com',
+  output: 'static',
+  integrations: [
+    icon({
+      include: {
+        ph: ['app-window', 'terminal-window', 'brain', 'git-branch', 'arrow-right', 'arrow-up-right'],
+      },
+    }),
+    sitemap(),
+    starlight({
+      title: 'coding agent tips',
+      description:
+        'evidence-backed guidance for coding agents in production software, from individual projects to startups and big tech.',
+      customCss: ['./src/styles/global.css'],
+      components: {
+        Header: './src/components/StarlightHeader.astro',
+        PageSidebar: './src/components/StarlightPageSidebar.astro',
+        PageTitle: './src/components/StarlightPageTitle.astro',
+      },
+      social: [{ icon: 'github', label: 'GitHub', href: repository }],
+      editLink: { baseUrl: `${repository}/edit/main/` },
+      lastUpdated: false,
+      sidebar: [
+        {
+          label: 'guides',
+          items: [
+            { label: 'all guides', slug: 'guides' },
+            { label: 'codex', slug: 'guides/codex' },
+            { label: 'claude code', slug: 'guides/claude-code' },
+            { label: 'operating system', slug: 'guides/operating-system' },
+          ],
+        },
+        {
+          label: 'market',
+          items: [
+            { label: 'market map', slug: 'market' },
+            { label: 'hardware', slug: 'market/hardware' },
+          ],
+        },
+        {
+          label: 'field work',
+          items: [
+            { label: 'field lab', slug: 'field-lab' },
+            { label: 'method', slug: 'method' },
+            { label: 'changes', slug: 'changes' },
+            { label: 'legacy', slug: 'legacy' },
+          ],
+        },
+      ],
+    }),
+  ],
+});

bun.lock

@@ -1,26 +1,41 @@
-# guide index
+---
+title: guides
+description: decision-oriented guides to codex, claude code, and shared agent engineering practice.
+products: [codex, claude-code]
+lastVerified: 2026-08-07
+status: current
+evidence: [source-verified, inference]
+sources: [openai-codex-manual, anthropic-claude-overview]
+evidenceRail:
+  - kind: source-verified
+    label: primary product guides
+    section: primary-guides
+  - kind: inference
+    label: decision-oriented structure
+    section: choosing-a-stack
+---
 
 the field guide is organized by decision rather than feature count.
 
 ## primary guides
 
-- [codex](./codex/README.md)
-- [claude code](./claude-code/README.md)
+- [codex](/guides/codex/)
+- [claude code](/guides/claude-code/)
 
 ## shared practice
 
-- [operating system](./shared/operating-system.md)
-- [methodology](./methodology.md)
-- [field lab](./field-lab/README.md)
-- [decision record](./decisions/README.md)
+- [operating system](/guides/operating-system/)
+- [methodology](/method/)
+- [field lab](/field-lab/)
+- [decision record](https://github.com/anipotts/coding-agent-tips/tree/main/docs/decisions)
 
 ## choosing a stack
 
-- [market map](./market/README.md)
-- [hardware economics](./market/hardware.md)
+- [market map](/market/)
+- [hardware economics](/market/hardware/)
 
 ## compatibility
 
-- [legacy tools](./legacy-tools.md)
+- [legacy tools](/legacy/)
 
-product facts are tracked in [sources.json](./sources.json). each page distinguishes hands-on evidence, source-verified facts, and inference.
+product facts are tracked in the repository [source registry](https://github.com/anipotts/coding-agent-tips/blob/main/docs/sources.json). each page distinguishes hands-on evidence, source-verified facts, and inference.

docs/README.md

@@ -0,0 +1,40 @@
+---
+title: latest changes
+description: material changes to the guide, its evidence, and its recommendations.
+products: [cross-runtime]
+lastVerified: 2026-08-07
+status: current
+evidence: [hands-on, source-verified]
+sources: [openai-codex-manual, anthropic-claude-overview]
+evidenceRail:
+  - kind: source-verified
+    label: codex manual review
+    section: '2026-08-07'
+    sourceId: openai-codex-manual
+  - kind: source-verified
+    label: claude code 2.1.224 review
+    section: '2026-08-07'
+    sourceId: anthropic-claude-overview
+  - kind: hands-on
+    label: field guide v4 reset
+    section: '2026-08-07'
+---
+
+## 2026-08-07
+
+### field guide v4 reset
+
+- reframed the repository around codex and claude code as co-equal primary guides.
+- added the surface, harness, model, and orchestration taxonomy.
+- replaced activity automation with read-only source and build verification.
+- established the field lab, evidence rail, and public decision record.
+- froze historical claude code tools through 2026-11-05.
+
+### source review
+
+- codex guidance was checked against the official manual and package 0.147.0.
+- claude code guidance was checked against official documentation and package 2.1.224.
+- current claude code hands-on comparison remains pending.
+
+changes below this point belong to the legacy tool era and remain available in
+the repository [changelog](https://github.com/anipotts/coding-agent-tips/blob/main/CHANGELOG.md).

docs/changes.md

@@ -1,14 +1,36 @@
-# claude code field guide
-
-<!-- guide-meta: {"products":["claude-code"],"last_verified":"2026-08-07","evidence":["source-verified"],"source_ids":["anthropic-claude-overview","anthropic-features-overview","anthropic-desktop"]} -->
+---
+title: claude code field guide
+description: source-verified guidance for claude code terminal, desktop, ide, agents, hooks, and permissions.
+products: [claude-code]
+lastVerified: 2026-08-07
+status: pending
+evidence: [source-verified, unknown]
+sources: [anthropic-claude-overview, anthropic-features-overview, anthropic-desktop]
+evidenceRail:
+  - kind: source-verified
+    label: claude code overview
+    section: current-shape
+    sourceId: anthropic-claude-overview
+  - kind: source-verified
+    label: current features
+    section: skills-hooks-plugins-and-agents
+    sourceId: anthropic-features-overview
+  - kind: source-verified
+    label: desktop documentation
+    section: desktop-and-context-switch-cost
+    sourceId: anthropic-desktop
+  - kind: unknown
+    label: current hands-on rerun pending
+    section: professional-default
+---
 
 evidence: historical hands-on use; current capabilities are source-verified through 2.1.224
 
 last verified: 2026-08-07
 
 primary source: [official claude code documentation](https://code.claude.com/docs/en)
 
-local note: 2.1.220 is installed, but the current hands-on protocol in [methodology](../methodology.md) has not been rerun for this reset. recommendations below that depend on current product behavior are therefore source-verified rather than presented as fresh comparative testing.
+local note: 2.1.220 is installed, but the current hands-on protocol in [methodology](/method/) has not been rerun for this reset. recommendations below that depend on current product behavior are therefore source-verified rather than presented as fresh comparative testing.
 
 ## current shape
 

docs/claude-code/README.md

@@ -1,6 +1,27 @@
-# codex field guide
-
-<!-- guide-meta: {"products":["codex"],"last_verified":"2026-08-07","evidence":["hands-on","source-verified"],"source_ids":["openai-codex-manual","git-worktrees"]} -->
+---
+title: codex field guide
+description: operating codex across cli, desktop, ide, cloud, worktrees, permissions, and durable configuration.
+products: [codex]
+lastVerified: 2026-08-07
+status: current
+evidence: [hands-on, source-verified, inference]
+sources: [openai-codex-manual, git-worktrees]
+evidenceRail:
+  - kind: source-verified
+    label: codex manual
+    section: current-shape
+    sourceId: openai-codex-manual
+  - kind: source-verified
+    label: git worktree behavior
+    section: worktrees-and-parallelism
+    sourceId: git-worktrees
+  - kind: hands-on
+    label: codex-cli 0.146.0
+    section: the-working-loop
+  - kind: inference
+    label: professional default
+    section: professional-default
+---
 
 evidence: hands-on through `codex-cli 0.146.0`; source-verified through 0.147.0
 

docs/codex/README.md

@@ -1,4 +1,22 @@
-# field lab
+---
+title: field lab
+description: reproducible scenarios, sanitized run records, public artifacts, and explicit limitations.
+products: [codex, claude-code]
+lastVerified: 2026-08-07
+status: current
+evidence: [hands-on, inference, unknown]
+sources: []
+evidenceRail:
+  - kind: hands-on
+    label: codex launch baseline
+    section: launch-baseline
+  - kind: inference
+    label: operator-centered protocol
+    section: interpretation
+  - kind: unknown
+    label: claude code rerun pending
+    section: launch-baseline
+---
 
 the field lab evaluates coding-agent systems through repeatable engineering work.
 it measures what the operator must understand, supervise, recover, and verify.
@@ -33,7 +51,7 @@ task specification.
 
 ## published data
 
-run records conform to [run.schema.json](./run.schema.json). public artifacts may
+run records conform to the repository [run schema](https://github.com/anipotts/coding-agent-tips/blob/main/docs/field-lab/run.schema.json). public artifacts may
 include commits, pull requests, test logs, screenshots, and concise design-review
 notes.
 

docs/field-lab/README.md

@@ -1,6 +1,20 @@
-# legacy claude code tools
-
-<!-- guide-meta: {"products":["cc","lore","time"],"last_verified":"2026-08-07","evidence":["retired"],"source_ids":["anthropic-features-overview"]} -->
+---
+title: legacy claude code tools
+description: compatibility and retirement policy for the historical cc, lore, time, hook, and example surfaces.
+products: [cc, lore, time]
+lastVerified: 2026-08-07
+status: legacy
+evidence: [source-verified]
+sources: [anthropic-features-overview]
+evidenceRail:
+  - kind: source-verified
+    label: current native features
+    section: why-the-tools-are-retiring
+    sourceId: anthropic-features-overview
+  - kind: unknown
+    label: no automatic migration parity
+    section: migration
+---
 
 status: retired from active development
 

docs/legacy-tools.md

@@ -1,6 +1,25 @@
-# market map for coding-agent systems
-
-<!-- guide-meta: {"products":["market"],"last_verified":"2026-08-07","evidence":["hands-on","source-verified","inference"],"source_ids":["openai-codex-manual","anthropic-claude-overview","vscode-agent-host","cursor-docs","conductor-harnesses","t3-code","opencode","kimi-code","kimi-k3","qwen-code","qwen-models","grok-build","grok-4-5"]} -->
+---
+title: market map for coding-agent systems
+description: choose a coding-agent stack by separating surfaces, harnesses, models, and orchestration.
+products: [market]
+lastVerified: 2026-08-07
+status: current
+evidence: [hands-on, source-verified, inference]
+sources: [openai-codex-manual, anthropic-claude-overview, vscode-agent-host, cursor-docs, conductor-harnesses, t3-code, opencode, kimi-code, kimi-k3, qwen-code, qwen-models, grok-build, grok-4-5]
+evidenceRail:
+  - kind: hands-on
+    label: current codex use
+    section: contender-map
+  - kind: source-verified
+    label: official product sources
+    section: contender-map
+  - kind: inference
+    label: operating-model recommendations
+    section: chooser-with-defaults
+  - kind: unknown
+    label: products awaiting hands-on review
+    section: contender-map
+---
 
 evidence: codex is current hands-on; claude code combines historical use with current source verification; other products are source-verified
 
@@ -94,7 +113,7 @@ subscription or token price is only one part of the system:
 - maintenance cost: config, plugins, provider adapters, updates, and policy.
 - reliability cost: recovery when a session, model, network request, or tool call fails.
 
-the [hardware guide](./hardware.md) covers the local resource side.
+the [hardware guide](/market/hardware/) covers the local resource side.
 
 ## recommendation