Design Log #03 — Agent Kit Documentation Pages

Written for AI agents. See Log Methodology Note below for details.

Background

The jay-website agent-kit directory contains comprehensive guides for building Jay Stack applications, organized by role: contracts, designer, developer, devops, and plugin. These guides are generated by jay-stack-cli agent-kit and cover everything from template syntax to deployment. Currently they're only consumed by AI agents and developers reading the repo directly.

DL#01 — Design log import (established the markdown-pages pattern)
DL#02 — Multi-repo design log sync (established multi-section routing)

Problem

The agent-kit guides are the most complete documentation of how to use Jay Stack, but they're not published on the website. We want to create a /docs section that exposes this content as browsable pages. The structure should mirror the agent-kit organization.

The existing agent-kit/INSTRUCTIONS.md is a terse routing file for agents — it doesn't explain what the agent-kit is or why documentation is written for AI agents. The docs section needs a proper landing page.

Design

Route structure

/docs                    ← Home: custom landing page explaining the agent-kit concept
/docs/contracts/[slug]   ← Contract authoring guides
/docs/designer/[slug]    ← Designer role guides
/docs/developer/[slug]   ← Developer role guides
/docs/devops/[slug]      ← DevOps role guides
/docs/plugin/[slug]      ← Plugin developer guides

Docs home (`content/docs/home.md`)

A custom markdown page (not from agent-kit) that explains:

What the Agent Kit is — documentation written for AI agents, readable by humans
Why documentation for agents is different — specification-style prose, role boundaries
The 5 roles with spider icon images (reused from the homepage) and links to each section

Preprocessing script (`scripts/sync-agent-kit-docs.cjs`)

Despite agent-kit files being local, we preprocess them into content/docs/{role}/ to inject notes. The script:

Copies markdown files from agent-kit/{role}/ to content/docs/{role}/
Injects a short note after the first heading: "Part of the Agent Kit — documentation written for AI agents"
Appends a full note at the bottom explaining what the Agent Kit is, linking back to /docs

Run via yarn sync:docs.

Note injection

Similar to DL#01's design log notes, each agent-kit page gets:

After first heading:

Part of the Agent Kit — documentation written for AI agents, readable by humans.

At the bottom:

This page is part of the Jay Stack Agent Kit — documentation generated from the framework source and written primarily for AI agents. The language and structure are optimized for machine consumption. Learn more about the Agent Kit →

Homepage integration

The 4 role cards on the homepage (Designer, Developer, Plugin Developer, DevOps — each with spider icon) are wrapped in links to /docs/{role}/instructions. This makes the homepage a natural entry point to the docs.

Page templates

Each role gets a src/pages/docs/{role}/[slug]/page.jay-html using markdown-pages with contentDir: content/docs/{role}. Reuses the design-log markdown styling.

Implementation Results

Implemented as designed.

scripts/sync-agent-kit-docs.cjs — preprocesses 69 files across 5 roles
content/docs/home.md — docs landing page with spider images and role descriptions
Homepage role cards now link to /docs/{role}/instructions
Page templates still need to be created (Phase 2)

Log Methodology Note

Note: These design logs are written primarily for AI agents as part of the Design Log methodology and made accessible here for human readers. The language and structure are optimized for machine consumption — expect precise, specification-style prose rather than narrative documentation.

Agent-Kit Documentation Pages