docs/public/ is the source for kandev.ai/docs. Pull requests validate this tree. After a push to main, .github/workflows/notify-docs.yml validates it again and, when the deploy hook is configured, calls Landing; a validation failure prevents publication.

The published docs have two audiences:

Use Kandev covers product tasks, configuration, limits, security, and operations.
Contribute to Kandev covers code ownership, development, testing, extension points, releases, and docs maintenance.

Keep implementation detail in contributor pages. A user guide should explain the supported behavior and link here when internal context is useful.

Choose a content type

Audience and content type are separate decisions. Keep the existing Use Kandev and Contribute to Kandev audience split, then choose one primary Diátaxis type for each page:

Tutorial: teach a beginner by leading them through one successful outcome.
How-to guide: help a reader complete a known task, including the relevant choices and recovery paths.
Reference: provide accurate, complete lookup information such as fields, commands, defaults, limits, or protocol contracts.
Explanation: build understanding of a concept, boundary, rationale, or trade-off.

Keep one dominant type per page. A page can link to other types, but a long tutorial, procedure, reference inventory, and architectural explanation should not compete for ownership on the same page. When an existing page mixes types, preserve its slug first and split only when the sections have different reader goals, owners, or maintenance lifecycles.

Write for scanning

Readers should be able to reach a first result, complete a task, answer a lookup question, or understand a concept without reading a different kind of page. Let the content type determine the structure:

Tutorials lead with prerequisites and a linear first success.
How-to guides lead with the task, expected result, and focused steps.
Reference pages lead with scope and stable lookup headings; a minimal example is optional and should not turn the page into a tutorial.
Explanation pages lead with the concept or question, then cover rationale, boundaries, and trade-offs.

Apply these scanning rules to every type:

Open with one sentence that says who the page is for and what it enables, explains, or defines.
Put required steps, the lookup scope, or the central concept near the top.
Use bullets for choices, limits, prerequisites, and consequences.
Keep paragraphs to one idea and normally no more than three sentences.
Link to the owning reference instead of repeating its detail.

Use a table only when readers must compare several options. Do not turn a page into a complete inventory of UI labels, implementation behavior, or exception cases.

Put useful but non-essential detail behind a native disclosure. Good candidates include exhaustive provider differences, compatibility notes, rare recovery paths, and background implementation behavior. Do not hide the required steps, security warnings, destructive effects, or a limitation that changes whether a feature can be used.

<details>
<summary>Advanced configuration and edge cases</summary>

Keep the detail concise, and link to the full reference when it grows.
</details>

Reference pages may be longer, but should optimize for lookup: state their scope, exact contract, availability, and important limits before the exhaustive details. Use stable headings, field names, command names, and examples where they improve lookup. Move procedures and rationale to linked how-to or explanation pages. Delete repeated explanations; one page should own each detailed contract.

Update an existing page

Edit the Markdown source and verify every command, setting, label, default, platform claim, and screenshot against current source or tests. Preserve the filename when possible: it is the public slug.

Use source-relative links such as [CLI](cli.md). Publication rewrites links between public pages to /docs/... and links to repository files outside docs/public/ to GitHub. Do not use site-root links or local machine paths.

State whether behavior is default, optional, platform-dependent, experimental, feature-flagged, internal, or still in progress. An ADR, spec, hidden route, or source package is not evidence that a feature is generally available.

Mark experimental content

Use page-level status when the whole guide describes an experimental surface:

---
title: "Kubernetes"
description: "Deploy Kandev to Kubernetes."
status: experimental
---

The docs header renders a visible status callout from that frontmatter. To invoke this experimental page indicator, use the exact value experimental; omit status for stable pages. Source validation rejects other page-status values. The separate stable, beta, and experimental values in coverage.json describe inventory stability and do not create page badges.

Use a section-level indicator when a stable guide contains one experimental capability. Keep this source syntax as Markdown so older renderers and GitHub still show an explicit callout; the publication layer upgrades it to the styled status component:

## Office dependencies

> [!EXPERIMENTAL]
> Office is feature-flagged and its dependency editor is not stable yet.

When Office is enabled, it can record blocked-by relationships between tasks. Use parent/child structure and workflow gates for the supported regular-Kanban path.

Place the indicator immediately after a descriptive heading that names the experimental capability, then follow it with the instructions or behavior it qualifies. Explain the enabling condition, current limit, and supported alternative. Do not drop a warning between otherwise stable paragraphs or create a standalone status section whose only content is the warning. The publication pipeline converts the callout to FeatureStatus and opts the generated page into MDX automatically.

Add a page

Search existing pages, choose Use Kandev or Contribute to Kandev, identify the page's primary content type, and record the audience and type in the PR body.
Create a lowercase, kebab-case Markdown file in docs/public/. The filename becomes the stable route; custom-executors.md publishes as /docs/custom-executors.

Add non-empty title and description frontmatter, then one level-one heading:

---
title: "Custom Executors"
description: "Configure a custom executor for Kandev tasks."
---

# Custom Executors

Add the slug, without .md, exactly once to docs/public/meta.json under the correct audience heading. Its position controls sidebar order. README.md is the maintenance guide and is not a published page.
Add the page to at least one area in docs/public/coverage.json, with current implementation and test evidence.
Link the page from the relevant overview and neighboring guides.
Match the page structure to its type: a linear path for tutorials, focused steps for how-to guides, stable lookup sections for reference, and concepts or trade-offs for explanations. Put secondary detail in a disclosure or the owning page.

The validator rejects missing frontmatter, pages absent from navigation or coverage, duplicate or unknown navigation entries, broken local files or heading fragments, missing assets, and site-root links.

Maintain feature coverage

docs/public/coverage.json is the source-backed map from shipped product areas to their user, operator, contributor, or integrator documentation. Every area cites concrete source and test files. The validator also discovers every static Settings route and registered Kandev MCP tool, then requires each one to have exactly one coverage owner or an explicit exclusion with a reason.

When behavior changes:

Update the owning page and its support boundary.
Update the area's source or test evidence when ownership moved.
Assign a new Settings route or MCP tool to the appropriate area.
Add a new area only when the behavior has a distinct audience, stability, and documentation owner.

Do not use the inventory to claim that a route, package, ADR, test harness, or feature flag is generally available. The page must still explain whether the user-facing behavior is stable, dependency-bound, limited, experimental, or unavailable.

Assets and diagrams

Store product screenshots under docs/screenshots/ and reference them relatively.
Do not hotlink mutable third-party images or commit temporary capture output.
Mermaid diagrams are supported. Keep them readable at docs-column width and explain the essential result in prose.
Prefer text and commands when the UI changes frequently.

Use a short focused video only when motion or interaction order communicates something that prose and a still image cannot. Store reviewed deliverables under docs/public/media/feature-guides/ as a WebM, an H.264 MP4 fallback, and a WebP poster. Keep raw captures, browser profiles, and temporary encoder output outside the repository.

Embed the local sources with the publication component:

<DocsVideo
  webm="./media/feature-guides/review.webm"
  mp4="./media/feature-guides/review.mp4"
  poster="./media/feature-guides/review.webp"
  title="Review a focused diff"
  caption="Inspect a changed line and leave feedback for the agent."
/>

Videos must show current isolated test data, avoid real credentials and production repositories, use native controls, and remain understandable from the poster and caption. Prefer a compact view that follows the relevant cursor or touch target over a wide application recording. Keep manifest.json and NOTES.txt beside the reviewed triplets. Source validation checks accepted QA status, the 960x600/25fps/no-audio delivery contract, page and section ownership, complete embeds, byte counts, SHA-256 hashes, and orphaned files. Do not add Markdown files under docs/public/media/ because public Markdown is treated as a page.

Validate the source

Run the dependency-free checks from the Kandev repository root:

node --test scripts/validate-public-docs.test.mjs
node scripts/validate-public-docs.mjs

make test-scripts runs the validator's unit tests among other repository script tests; it does not replace the live validation command above.

Verify the Landing publication build

With kdlbs/landing checked out beside kandev, use Landing's documented Node 24.12.0 and pnpm 10.29.3 prerequisites and build the same root-plus-docs artifact deployed to Cloudflare Pages:

cd ../landing
pnpm install --frozen-lockfile
KANDEV_DOCS_SOURCE_PATH="$(cd ../kandev && pwd)/docs" pnpm build:pages

KANDEV_DOCS_SOURCE_PATH makes Landing fetch the local public pages instead of GitHub. Pass an absolute path because the docs package runs its prebuild from landing/apps/docs. The build copies only pages named by meta.json, rewrites links, and builds both the landing site and docs route. Do not commit generated Landing content, .next, or out directories.

Before review, confirm:

each new or renamed page appears exactly once in meta.json;
links resolve relative to their source file;
claims are supported by current code, tests, or workflows;
conditional support and platform limits are explicit;
the PR body states the audience and primary content type for each new or changed page;
source validation and, for publication-sensitive changes, the Landing build pass.