{"id":24,"type":"docs","title":"Web Blog Agent Handbook","slug":"web-blog-agent-handbook","canonicalUrl":"https://docs.phatysd.me/content/web-blog-agent-handbook","status":"published","revision":2,"publishedAt":"2026-09-19T16:34:11.292Z","updatedAt":"2026-09-19T16:34:11.292Z","hierarchyPath":"Web Blog > Agent Operations","topics":["Agent operations","Next.js 16","Repository workflow"],"tags":["agents","handbook","nextjs","workflow"],"related":[{"slug":"nextjs-16-agent-first-guide","title":"Next.js 16 for Agents: A Verifiable, Production-Ready App Router Guide","type":"docs","canonicalUrl":"https://docs.phatysd.me/content/nextjs-16-agent-first-guide"},{"slug":"public-content-contract-v1","title":"Public Content Contract v1","type":"docs","canonicalUrl":"https://docs.phatysd.me/content/public-content-contract-v1"},{"slug":"deployment-runbook-heroku-cloudflare","title":"Deployment Runbook: Heroku + Cloudflare","type":"docs","canonicalUrl":"https://docs.phatysd.me/content/deployment-runbook-heroku-cloudflare"}],"body":"# Web Blog Agent Handbook\n\nThis handbook is the operating manual for an agent working in the `web-blog` repository. It explains how to inspect the project, make scoped changes, publish content, and prove that the result works in production.\n\n## Repository map\n\n```text\napp/\n  page.tsx                         public home\n  content/[slug]/page.tsx         human-readable content page\n  content/[slug]/json/route.ts    machine-readable JSON\n  content/[slug]/markdown/route.ts machine-readable Markdown\n  dashboard/                       owner-only authoring workspace\n  api/auth/[...nextauth]/          Auth.js handlers\n  llms.txt/route.ts                agent discovery index\n  sitemap.ts                       XML discovery index\nsrc/db/schema.ts                   content_items and content_revisions\nsrc/lib/public-content.ts         published-content queries and URLs\nsrc/lib/agent-content.ts          agent JSON/Markdown representation\nsrc/lib/content.ts                draft parsing and validation\nsrc/lib/db.ts                     Drizzle/Postgres connection\nauth.ts                            GitLab/Auth.js configuration\ndrizzle/                           generated SQL migrations\ndocs/contracts/                    public contracts\ndocs/specs/                        product specifications\ndocs/tasks/                        implementation tasks\n```\n\nThe public content source of truth is the database. `content_items` stores the current published item and `content_revisions` stores immutable published snapshots. A local Markdown file can be a research or authoring source, but it is not public until it is published through the dashboard workflow or a controlled database operation.\n\n## Commands\n\nUse the commands already declared by `package.json`; do not invent alternatives:\n\n```bash\nnpm run dev          # local development\nnpm run build        # production build\nnpm run start        # serve the production build\nnpm run lint         # ESLint\nnpm run typecheck    # TypeScript\nnpm run db:generate  # generate Drizzle SQL\nnpm run db:migrate   # apply migrations to DATABASE_URL\nnpm run db:seed      # demo data only; never run in production casually\n```\n\nBefore running a database command, identify which `DATABASE_URL` is loaded. `.env.local` is for local work; Heroku config vars are for production. Never print a database URL or copy a production credential into a file.\n\n## Agent workflow\n\n### Before editing\n\n1. Read `AGENTS.md`.\n2. Read the relevant requirement, specification, task, ADR, or contract.\n3. Confirm the installed versions in `package.json` and the lockfile.\n4. Inspect the existing route, schema, data access, and tests.\n5. Write down `Observed`, `Inferred`, `Unknown`, and the smallest change needed.\n\n### During implementation\n\n- Keep Server Components server-side unless interaction requires a Client Component.\n- Keep database clients, credentials, OAuth secrets, and request-time environment variables server-only.\n- Treat Server Actions and Route Handlers as public boundaries: authenticate, authorize, validate, and return narrow data.\n- Keep the canonical slug stable after publication.\n- Update cache or route invalidation whenever a mutation changes public content.\n- Preserve unrelated user changes in a dirty worktree.\n- Do not run seed commands against production unless the task explicitly says to do so.\n\n### Content workflow\n\nFor a new content item, choose `blog`, `docs`, or `template`, then define its title, canonical slug, hierarchy path, topics, tags, body, and related slugs. Save as draft while editing. Publish only after the body and metadata pass validation. Publishing increments the revision number and writes a revision snapshot.\n\nFor a revision, keep the slug unchanged. Update the current item and insert a new row in `content_revisions` in one transaction. Do not delete old revisions just to simplify a UI.\n\n## Server and client boundary\n\nPages, layouts, metadata, database reads, and public rendering are Server Component territory by default. Add `'use client'` only to the smallest interactive leaf that needs state or browser APIs. A Client Component must never receive a secret, database client, or unrestricted internal record.\n\nIn Next.js 16, request APIs such as `params` and `searchParams` are asynchronous. Use `await` in pages, layouts, metadata, and Route Handlers. Do not copy a synchronous example from an older tutorial.\n\n## Verification checklist\n\nBefore reporting completion, run the checks appropriate to the change:\n\n```bash\nnpm run typecheck\nnpm run lint\nnpm run build\n```\n\nThen smoke-test the real boundary. For public content, check the human page, `/markdown`, `/json`, `/sitemap.xml`, and `/llms.txt`. For auth, check the sign-in page, provider redirect, callback, session, and owner gate. For database work, check migrations, SSL, transaction behavior, and row counts without revealing credentials.\n\nReport the exact commands, status codes, URLs, and known warnings. A successful build alone is not proof that OAuth, DNS, TLS, or data freshness works.\n\n## Primary references\n\n- [Next.js AI Coding Agents](https://nextjs.org/docs/app/guides/ai-agents)\n- [Next.js App Router](https://nextjs.org/docs/app)\n- [Next.js 16 upgrade guide](https://nextjs.org/docs/app/guides/upgrading/version-16)\n- Repository sources: `docs/workflow.md`, `docs/contracts/public-content.md`, and `docs/adr/0003-agent-readable-public-content.md`.\n"}