Public Docs Maintenance

Public Docs Maintenance

Use this skill when work touches public-docs/ or materially changes shipped user workflows, public contracts, or operator decisions.

Source of truth

• AGENTS.md
• public-docs/
• scripts/docs/public-docs/public-docs-map.mjs
• generated reference inputs from packages/cli/src/commands/** and packages/contracts/src/contracts/**
• current-state engineering docs under docs/ only as implementation context, not as publishable copy

Public docs intent

• The public site is for Compartment users and operators, not repo contributors.
• Public docs explain commands, configuration choices, externally visible behavior, limits, and user responsibilities.
• Engineering docs, architecture docs, runtime topology, proposal specs, and review follow-ups stay outside the public site.

Docs threshold

• Do not document every user-visible change.
• Update public docs only when users must change what they do, understand a public contract, make a configuration/security/compatibility decision, or account for externally visible lifecycle behavior.
• Public contract and generated-reference inputs still count; regenerate reference without adding prose when that is enough.
• Example: a checkbox default changing does not need a docs paragraph unless it changes setup steps, permissions, security, compatibility, or another operator decision.

What to include

• Style preferences:
  • write directly and concretely;
  • use active voice and second person when it helps;
  • prefer current commands, current file names, and observable outcomes over implementation mechanics;
  • avoid hype, filler, and generic “why this matters” padding.
• Code standards:
  • prefer real compartment CLI commands;
  • prefer minimal valid YAML for compartment.yml and compartment.routes.yml;
  • do not use foo, bar, or placeholder hostnames when a concrete example is clearer.
• Content requirements:
  • guides should usually include purpose, main steps, important constraints, externally visible automation, and next steps;
  • major shipped features usually need an updated overview plus at least one task guide;
  • generated reference or a small overview edit is not enough when users need a new workflow, public concept, or mental model;
  • reference pages should stay generated when the source is deterministic;
  • for curated docs pages, the last URL path segment should match the page title in a predictable normalized form;
  • CLI reference pages are the exception: when the title would create duplicate last path segments, add the smallest useful unique path part instead of forcing identical slugs;
  • do not duplicate generated reference content in long hand-written pages when a short explanation plus a reference link is enough;
  • describe background behavior by its user-visible effect, schedule, retention, expiry, limits, or required action; do not describe libraries, queues, database tables, process boundaries, or service topology unless those details change an installation or incident-response decision.
• Product context:
  • Compartment is CLI-first;
  • installs, orgs, projects, environments, services, deployments, domains, variables, and access are the canonical public nouns;
  • internal docs under docs/specs/* may mix shipped decisions and future proposals; do not describe behavior as shipped unless current code or existing public docs confirm it.