---
name: document-authoring
description: Strict standard operating procedure for human and AI authors writing, formatting, translating, and structuring documentation across the ALNEAS ecosystem.
---

# Document Authoring Skill & Standard Operating Procedure (ALNEAS)

This skill governs how AI agents (Antigravity, Codex, Claude) and human contributors author, review, structure, and translate documentation across the ALNEAS projects EAOS, Appkit, SiteKit and `github-docs`. Appkit currently retains the `tools` portal ID and SiteKit the `web-framework` portal ID; verify package names in the owning manifests.

## Adopting the standards in a project

When adding or aligning a project's agent instructions, use the
[project documentation instruction template](https://tech-docs.alneas.com/templates/project-documentation-instructions.md).
Keep policy and skill references in AGENTS.md and add only verified project-specific
paths and checks. The template does not replace this skill or the shared policy.

## 1. Dual-Audience Design Mandate & EAOS Principles

Every document MUST be authored to satisfy two distinct consumers simultaneously:
1. **The Human Developer**: Demands fast scanning, visual hierarchy (tables, badges, code snippets), clear prerequisites, and zero fluff.
2. **The LLM / AI Assistant**: Demands explicit semantic boundaries, consistent frontmatter, unambiguous type signatures, and clear context scoping to prevent hallucinations.

### Inherited EAOS Core Principles:
- **Role Separation**: Distinguish human usage guides, machine-readable API specifications, and internal AI action skills. Never substitute an API specification with an AI skill.
- **AI Index Role**: Files like `llms.txt` or meta-indexes act strictly as roadmaps to detailed documents, never as duplicate silos of type definitions.
- **Generation Protection**: Never manually edit files in generated targets (`src/content/docs/**/api.md` or `generated/`). Edits must be made to source JSDocs or the translation dictionary.

---

## 2. Diátaxis Framework Selection

Before writing or editing any page, you MUST identify its exact **Diátaxis Archetype** and adhere strictly to its format:

### A. Tutorial (`archetype: tutorial`)
- **Goal**: Onboarding a beginner from 0 to 1 in under 10 minutes.
- **Rules**:
  - Provide a numbered, linear series of steps.
  - Zero choice/branching: specify exact commands (`bun install`, `bun run dev`).
  - Show the expected output after each command.
  - End with a working milestone.

### B. How-To Guide (`archetype: how-to`)
- **Goal**: Helping an experienced user accomplish a real-world task.
- **Rules**:
  - Start with a clear **Prerequisites** section.
  - Focus on the goal (e.g., "How to register custom circuit breakers").
  - Do not explain foundational theory here; link to an Explanation doc instead.

### C. Reference (`archetype: reference`)
- **Goal**: Machine-precise descriptions of APIs, CLI flags, configuration schemas, and types.
- **Rules**:
  - Follow the **Structured Card / Swagger Style**:
    1. Signature & Badge (`[FUNCTION]`, `[CLASS]`, `[GET]`, `[POST]`).
    2. Description (1 sentence summary).
    3. Parameters table (Name, Type, Required, Description).
    4. Return value & Type.
    5. Copy-pasteable example snippet with imports.

### D. Explanation (`archetype: explanation`)
- **Goal**: Clarifying design decisions, architectural boundaries, security policies, and trade-offs.
- **Rules**:
  - Explain *why* things work the way they do (e.g., "Why we isolate execution behind approval gates").
  - Use Mermaid diagrams (`sequenceDiagram`, `flowchart TD`) for visual architecture.

---

## 2.1 Project Landing Standard (The 5-Section Template)

When creating or reviewing a project or package landing page (`index.md` / README), you MUST enforce the following 5-section sequence:

1. **Elevator Pitch**: 1 punchy sentence stating *who it is for* and *what it solves*.
2. **Why & Value**: 2-3 lines explaining why this exists and what advantages it delivers over existing alternatives.
3. **Key Highlights**: 3-4 bullet points or cards highlighting core architectural features.
4. **Quickstart**: A copy-pasteable minimal example including installation command (`bun add ...`) and imports.
5. **Next Steps**: Navigation links directing readers to the API Reference, Architecture Guides, or Sub-modules.


### GitHub and npm README contract

Repository and package READMEs use plain Markdown with these first five H2
sections, in order: `Elevator Pitch`, `Why & Value`, `Key Highlights`,
`Quickstart`, `Next Steps`. Existing `Why & Value Proposition` headings are
accepted as the same section. Keep 3-4 top-level highlights. Preserve detailed
runtime, licensing and distribution requirements after the introduction.

Repository Quickstarts show real setup/check commands. Package Quickstarts show
installation of the package name (or its exact verified local archive before
publication), an exact supported public import, and relevant peers/styles/host
requirements. Never present an unpublished registry name as already available.
Use README source as the introduction's single source; generate portal metadata
wrappers and rewrite their links rather than maintaining a second introduction.

Check links in both repository and package contexts. A sibling source file or
ignored generated directory is not a portable npm/GitHub link: use a canonical
HTTPS guide when the target is outside either published context. Before release,
inspect the actual packed README and link targets. After authorized publication,
compare the destination README with its source; local generation does not update
GitHub or npm by itself.

Each owning repository records its README paths in `readme-policy.json` and
runs the [portable checker](https://tech-docs.alneas.com/templates/readme/check-readmes.mjs)
and its regression tests through its existing documentation gate. Keep a reviewed
local copy for offline CI. This structural check does not certify factual claims,
example runtime behavior, all peer prerequisites or JSDoc completeness; retain
stronger project-specific checks and review those contracts against implementation.

## 2.2 Sub-page Standards (Topic Guides, API, Architecture)

When authoring non-landing sub-pages, follow these exact layout contracts:

- **How-To / Topic Guides (`/guides/<name>.md`)**:
  - `## Prerequisites`: Required packages, environment variables, or background knowledge.
  - `## Step-by-Step Implementation`: Code blocks with full imports and explanation.
  - `## Verification`: Expected outputs, test commands, or console logs.
  - `## Troubleshooting / Common Pitfalls`: Specific error symptoms and their remedies.

- **API Reference (`/api.md`)**:
  - Follow the **Structured Card / Swagger Standard** without conversational fluff. Must include badge (`[FUNCTION]`, `[CLASS]`), TypeScript signature, parameters table, return type, and copy-pasteable usage example.

- **Architecture & Design (`/architecture.md`)**:
  - `## Motivation`: Problem statement and boundaries.
  - `## Architectural Diagram`: Use Mermaid (`sequenceDiagram` or `flowchart TD`).
  - `## Trade-offs & Decisions`: Why alternative designs were rejected.

- **Package Documentation (Appkit)**:
  The public Appkit repository owns `@alneas/appkit-core` and `@alneas/appkit-react`.
  The portal project ID remains `tools` for URL compatibility. Order each package's
  overview at `sidebar.order: 1`, feature guides at `2-9`, exports at `10`, and
  environment/verification references at `20` when present. Verify current exports
  rather than restoring obsolete package chapters from the former tools layout.

---

### Feature import contract

Every feature guide must include a `## Public import` section with its exact published import subpath and use that target in a self-contained example. Do this on each feature page, not only in a package-wide exports table.

Keep installation commands at the npm package name (for example, `bun add @scope/package`); use feature paths only in imports (for example, `@scope/package/feature`). Check the owning manifest's `exports` rather than inferring paths from source directories. Document feature-specific peers, CSS, providers and runtime requirements. During renames or package consolidation, update guides, examples, JSDoc imports and AI indexes together and run the owning project's subpath checks.

## Generated documentation freshness: implement the owning project's check

When adopting these standards or changing documentation generation inputs:

1. Inspect the owning project's canonical sources, generated files, generation
   commands and existing documentation/CI gates. Include README portal wrappers,
   exports references, manifests, AI indexes and consumer metadata where present.
2. Check whether an automated temporary-regeneration comparison already covers
   all of those outputs. A build, existing files, a URL reference or a manual
   comparison is not sufficient.
3. If integration is missing, implement it in that owning project as part of the
   authorized documentation task, without requiring another reminder. Use the
   [shared checker and tested setup](https://tech-docs.alneas.com/templates/generated/README.md)
   or retain an existing equivalent or stronger check. Adapt the generator to
   honor a temporary output directory for every write; keep canonical reads and
   same-run generated dependencies correct. The checker is not a sandbox for
   arbitrary generators, so verify this behavior with the project's tests.
4. Record verified command/output paths in `generated-policy.json` (or the
   existing equivalent), keep reviewed checker/tests locally, and connect them to
   the existing documentation and applicable CI/release gates. Do not fetch and
   execute changing remote code during CI. Keep project-owned paths and commands
   in AGENTS.md; shared rules remain at the policy and skill URLs.
5. Demonstrate failures for changed, missing and obsolete output, generation
   errors, and noncompliant temporary-output behavior. Verify that the check does
   not repair normal outputs. Use the normal generator explicitly when updates
   are required, review those changes, then run the freshness/documentation checks.
6. Report actual commands and results. Do not describe a copied checker as
   integrated until the owning generator, output list and gate are connected.
   If no generated documentation exists, verify and report not-applicable. If
   integration is blocked, state what remains instead of claiming compliance.

Keep private sources and evidence in their owning repository. Do not commit,
push, deploy or publish a package merely to satisfy this workflow; those actions
require the applicable user authorization.

## 2.3 Public API JSDoc authoring

Apply the policy's public API JSDoc requirements to declarations reachable through supported package `exports`. Read the implementation, type declaration and existing tests before documenting behavior. Keep English JSDoc on the owning declaration; re-exports reference it. Review overload-specific contracts and public members as well as top-level functions.

For each new or changed public API:

1. Write a one-sentence purpose and behavior summary. Use English in the owning source project.
2. Add `@param` for every parameter and `@typeParam` for every type parameter. Explain semantics, units, constraints, callback contracts and actual defaults. Describe object members on the canonical interface/type, linking those declarations and noting call-specific restrictions. Document public class members, option/props properties and configuration values; use `@defaultValue` where supported for real property defaults.
3. Add `@returns` to non-constructor callables. Cover resolved async results, nullable/empty cases and ownership; for `void`/`Promise<void>`, describe completion without claiming a returned value. Do not add empty parameter tags to parameterless APIs or return tags to constructors.
4. Add `@throws` for known synchronous errors and Promise rejections, with triggering conditions. Distinguish returned failure data from thrown/rejected failures and document meaningful propagated adapter/callback errors. Do not fabricate error types or require placeholder throws tags when none apply.
5. Use `@remarks` or a linked canonical guide for applicable runtime/peer/CSS/provider requirements, host authorization, side effects, persistence, cleanup, cancellation, concurrency and retry/idempotency behavior. Include partial/uncertain outcomes where relevant. An import or type signature does not prove these guarantees.
6. Add `@example` to every public callable, class and component. Include the exact supported import, defined inputs and the relevant setup/cleanup; use TSX for component examples. Interfaces, type aliases and constants may link to a canonical usage example instead of duplicating one. Never use an empty-success host adapter to imply working authentication or persistence.
7. Add `@deprecated` when applicable, with the reason and replacement or an explicit absence of one. Verify any stated version or removal schedule.
8. Let TypeScript own types, signatures and optionality; avoid duplicate JSDoc `{Type}` annotations in TypeScript. Check that the owning renderer supports the chosen tags. Preserve required information in source and a rendered description/remarks field or linked guide if a tag is not rendered.
9. Type-check examples through normal consumer resolution, verify behavior-sensitive examples, regenerate API reference and run the owning project's documentation checks. Report unfilled documentation gaps; do not equate a successful build with complete JSDoc coverage. Do not hand-edit generated API cards.

Japanese API/JSDoc translation is performed in `github-docs` using its translation dictionary. Translate descriptions only; preserve identifiers, type signatures, imports and example code. This task does not move English JSDoc or its ownership into the portal.

---

## 3. Formatting & Style Rules

### Frontmatter Standard
Portal-ingested documents must begin with this structure. GitHub/npm READMEs must remain plain Markdown; generate a separate portal landing page with metadata from the README to avoid exposing frontmatter or maintaining two introductions by hand:
```yaml
---
title: "Clear, Self-Explanatory Title"
description: "Dense 1-2 sentence overview for search engines and AI context indexing."
sidebar:
  order: 10
archetype: "how-to" # tutorial | how-to | reference | explanation
project: "eaos-workspace" # eaos-workspace | tools | web-framework | portal
tags: ["core", "plugin-sdk"]
---
```

### Code Blocks & Links
- **Always specify the language**: ```` ```typescript ````, ```` ```bash ````, ```` ```json ````.
- **Self-contained examples**: Always include necessary `import` statements in code examples so they can be copied and run directly.
- **Clickable relative links**: Use Starlight-compatible relative links. Never use absolute filesystem links (`file:///Volumes/...`).

---

## 4. Bilingual Translation Protocol (EN -> JA)

### Ownership and working directory

- **English source ownership:** Each project owns its canonical English guides and English JSDoc. Edit API descriptions, parameter/return documentation and code examples in the owning source project, then regenerate its approved API reference. Preserve actual type signatures and exports; do not repair generated API pages by hand.
- **Japanese portal translation ownership:** `github-docs` owns creating, storing and updating Japanese portal translations. Follow this section from the `github-docs` checkout, even when another project invokes this skill. Do not create a `src/content/docs/ja/` tree in that other project for portal localization.
- Do not add or synchronize Japanese documents or upstream `sourceJa` entries solely for portal translation. If Japanese text was drafted upstream, transfer it to `github-docs` translation sources instead of establishing an upstream translation mirror.
- For manifest-ingested guides, edit `src/data/translations/pages/<projectId>/<slug>.md` in `github-docs`, then run ingestion to render `src/content/docs/ja/<projectId>/`. Maintain API/JSDoc translation strings in `src/data/translations/api-ja.json`; regenerate API pages instead of editing their output. Keep identifiers, signatures, imports and code snippets unchanged in translations.
- Project-owned Japanese UI strings, in-product help and runtime/package assets are a separate concern. Preserve them and their references unless the user explicitly requests their migration or removal. Portal translation ownership alone is not permission to delete them.

- **Root is English**: Always write canonical technical documentation in clear, idiomatic English.
- **Mirroring into Japanese**:
  - The Japanese portal output must be placed in `github-docs` at `src/content/docs/ja/<path>`; maintain manifest-ingested guide translation sources in the portal-owned directory specified above.
  - Maintain the exact same file path, frontmatter schema, and code snippets.
  - Translate descriptions, explanations, and parameter comments into professional technical Japanese (敬体: です・ます調, or 技術文書標準の である調 を一貫して使用).
  - Do NOT translate code identifiers, variable names, package names, or type names.

### 4.1 Running AI CLI Translation (Maintainer Workflow)
After approved English JSDoc or Markdown changes are ingested, maintainers run the translation pipeline **from the `github-docs` checkout**, using the preferred local AI CLI. Do not run or reproduce this portal translation workflow inside an upstream project:
```bash
# Auto-detect available engine (agy -> codex -> claude)
bun run translate

# Or specify explicitly
bun run translate --engine=antigravity # Google Antigravity (agy --print)
bun run translate --engine=codex       # OpenAI Codex CLI (codex exec)
bun run translate --engine=claude      # Anthropic Claude CLI (claude -p)
```
- Verify updated translations in `src/data/translations/api-ja.json` and `src/content/docs/ja/`.
- Commit the translation dictionary alongside documentation updates.


---

## 5. Security & Verification Checklist

Before saving, submitting, or committing any document, verify:
- [ ] No internal machine file paths (`/Volumes/...`, `/Users/...`, `file://`).
- [ ] No private enterprise details, secrets, operator tokens, or tenant IDs.
- [ ] Frontmatter contains valid `title`, `description`, `archetype`, and `project`.
- [ ] All code snippets are syntactically valid TypeScript/Bash.
- [ ] Registered in the project's `docs.manifest.json` (for cross-project ingestion).
- [ ] Pre-flight passes via `bun run ingest --verify --project=<manifest-path>`.
- [ ] `bun run build` succeeds cleanly without broken links or loader warnings.