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

  1. Read AGENTS.md.
  2. Read the relevant requirement, specification, task, ADR, or contract.
  3. Confirm the installed versions in package.json and the lockfile.
  4. Inspect the existing route, schema, data access, and tests.
  5. 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

Agent access

Choose a representation.

Published content only
Human pageYou are reading the human-facing canonical page.
Current page

Both machine-readable links refer to this same published item and preserve its identity, relationships, freshness, and body.