---
id: 24
type: docs
title: "Web Blog Agent Handbook"
slug: "web-blog-agent-handbook"
canonical_url: "https://docs.phatysd.me/content/web-blog-agent-handbook"
status: published
revision: 2
published_at: "2026-09-19T16:34:11.292Z"
updated_at: "2026-09-19T16:34:11.292Z"
hierarchy_path: "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
    canonical_url: "https://docs.phatysd.me/content/nextjs-16-agent-first-guide"
  - slug: "public-content-contract-v1"
    title: "Public Content Contract v1"
    type: docs
    canonical_url: "https://docs.phatysd.me/content/public-content-contract-v1"
  - slug: "deployment-runbook-heroku-cloudflare"
    title: "Deployment Runbook: Heroku + Cloudflare"
    type: docs
    canonical_url: "https://docs.phatysd.me/content/deployment-runbook-heroku-cloudflare"
---

# 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

```text
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:

```bash
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:

```bash
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](https://nextjs.org/docs/app/guides/ai-agents)
- [Next.js App Router](https://nextjs.org/docs/app)
- [Next.js 16 upgrade guide](https://nextjs.org/docs/app/guides/upgrading/version-16)
- Repository sources: `docs/workflow.md`, `docs/contracts/public-content.md`, and `docs/adr/0003-agent-readable-public-content.md`.
