Docs · Web Blog / Agent Operations
Web Blog Agent Handbook
Web Blog Agent Handbook
This 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.
Repository map
app/
page.tsx public home
content/[slug]/page.tsx human-readable content page
content/[slug]/json/route.ts machine-readable JSON
content/[slug]/markdown/route.ts machine-readable Markdown
dashboard/ owner-only authoring workspace
api/auth/[...nextauth]/ Auth.js handlers
llms.txt/route.ts agent discovery index
sitemap.ts XML discovery index
src/db/schema.ts content_items and content_revisions
src/lib/public-content.ts published-content queries and URLs
src/lib/agent-content.ts agent JSON/Markdown representation
src/lib/content.ts draft parsing and validation
src/lib/db.ts Drizzle/Postgres connection
auth.ts GitLab/Auth.js configuration
drizzle/ generated SQL migrations
docs/contracts/ public contracts
docs/specs/ product specifications
docs/tasks/ implementation tasks
The 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.
Commands
Use the commands already declared by package.json; do not invent alternatives:
npm run dev # local development
npm run build # production build
npm run start # serve the production build
npm run lint # ESLint
npm run typecheck # TypeScript
npm run db:generate # generate Drizzle SQL
npm run db:migrate # apply migrations to DATABASE_URL
npm run db:seed # demo data only; never run in production casually
Before 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.
Agent workflow
Before editing
- Read
AGENTS.md. - Read the relevant requirement, specification, task, ADR, or contract.
- Confirm the installed versions in
package.jsonand the lockfile. - Inspect the existing route, schema, data access, and tests.
- Write down
Observed,Inferred,Unknown, and the smallest change needed.
During implementation
- Keep Server Components server-side unless interaction requires a Client Component.
- Keep database clients, credentials, OAuth secrets, and request-time environment variables server-only.
- Treat Server Actions and Route Handlers as public boundaries: authenticate, authorize, validate, and return narrow data.
- Keep the canonical slug stable after publication.
- Update cache or route invalidation whenever a mutation changes public content.
- Preserve unrelated user changes in a dirty worktree.
- Do not run seed commands against production unless the task explicitly says to do so.
Content workflow
For 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.
For 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.
Server and client boundary
Pages, 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.
In 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.
Verification checklist
Before reporting completion, run the checks appropriate to the change:
npm run typecheck
npm run lint
npm run build
Then 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.
Report the exact commands, status codes, URLs, and known warnings. A successful build alone is not proof that OAuth, DNS, TLS, or data freshness works.
Primary references
- Next.js AI Coding Agents
- Next.js App Router
- Next.js 16 upgrade guide
- Repository sources:
docs/workflow.md,docs/contracts/public-content.md, anddocs/adr/0003-agent-readable-public-content.md.
Agent access
Choose a representation.
Both machine-readable links refer to this same published item and preserve its identity, relationships, freshness, and body.