Writing these docs

docs/ is an Antora documentation component, not a site. It contains no playbook: the main documentation site references this repository as a content source.

How the site consumes it

content:
  sources:
    - url: https://github.com/Payability/automatic-uw-tool.git
      branches: [release]
      start_path: docs

docs/antora.yml declares the component:

name: automatic-uw-tool
title: Automatic Underwriting Tool
version: ~                       # unversioned
start_page: ROOT:index.adoc
nav:
  - modules/ROOT/nav.adoc

version: ~ makes the component unversioned: the site always shows the state of the branch it tracks. If per-branch versions are ever wanted, switch to version: true (Antora derives the version from the branch or tag name) — that changes the published URLs, so coordinate with the site owners.

Attributes defined under asciidoc.attributes (automatic-uw-tool, https://github.com/Payability/automatic-uw-tool, 3.9, release, 605668041275, 625663093496, automatic-uw-tool-task-list, 80%) are soft-set with @, so the playbook can override any of them. Use them instead of repeating values that might change.

Layout

docs/
├── antora.yml                     component descriptor
└── modules/
    └── ROOT/
        ├── nav.adoc               the navigation tree (every page must be listed)
        ├── pages/                 one .adoc per page; subdirectories become URL segments
        │   ├── index.adoc
        │   ├── architecture.adoc
        │   ├── request-lifecycle.adoc
        │   ├── domain-model.adoc
        │   ├── processes/
        │   ├── api/
        │   ├── events/
        │   ├── data/
        │   ├── components/
        │   ├── operations/
        │   ├── contributing/
        │   └── reference/
        ├── partials/              reusable snippets, included as partial$<name>.adoc
        ├── examples/              literal payloads, included as example$<name>.json
        └── attachments/           downloadable files, linked as attachment$<name>

Conventions

One page, one subject. If a page needs two unrelated headings at level 2, it is probably two pages.
Page header — a level-0 title plus :navtitle: (short, for the sidebar) and :description: (one sentence).
Cross-references use the xref macro with the target’s path inside pages/ — for example xref:api/tasks.adoc[] or xref:api/tasks.adoc#execute-task[]. Empty brackets take the target’s title; add text only when the title does not read well in the sentence.
Anchors — give a section an explicit [#kebab-id] when other pages link to it. The component sets idprefix: '' and idseparator: '-', so generated ids are predictable.
Source paths are written in monospace (task/process.py) rather than linked, so they stay valid regardless of branch. The https://github.com/Payability/automatic-uw-tool/blob/release attribute is available if a real link is needed.
Code blocks are [source,python], [source,json], [source,bash], [source,yaml]. Keep quoted code short and current — quote the two or three lines that carry the rule, not whole methods, so the docs do not drift when the file moves.
Reused payloads live in examples/ and are included, so the same JSON is never pasted twice.
Admonitions — NOTE for context, IMPORTANT for a contract, WARNING for a foot-gun. Use them sparingly enough that they still stand out.
Tables need options="header" and explicit cols= weights. Escape a literal | inside a cell as \|.

Diagrams

Diagrams are written as Mermaid inside [source,mermaid] blocks. Without a diagram extension the site renders them as readable code; if the playbook enables asciidoctor-diagram or asciidoctor-kroki, change the block delimiter to [mermaid] (or [mermaid,name,svg]) to have them rendered as images. Keep the source terse enough to read either way.

Previewing locally

There is no playbook in this repository, so preview with a throwaway one:

# /tmp/local-playbook.yml
site:
  title: automatic-uw-tool (local)
  start_page: automatic-uw-tool::index.adoc
content:
  sources:
    - url: .                     # run from the repo root
      branches: HEAD
      start_path: docs
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

npx antora --fetch /tmp/local-playbook.yml && open build/site/index.html

branches: HEAD builds your working branch’s committed state. Antora reads from git, so uncommitted edits do not appear — commit (or use a local worktree) before previewing.

Quick sanity checks without Node: asciidoctor -o /dev/null docs/modules/ROOT/pages/*/.adoc catches syntax errors, though resource-id resolution (xref targets, partial$ and example$ includes) is Antora-specific and will warn.

Adding a page

Create docs/modules/ROOT/pages/<area>/<name>.adoc with a title, :navtitle: and :description:.
Add it to docs/modules/ROOT/nav.adoc under the right group — a page missing from the nav is published but unreachable.
Link it from the related pages, and from the "Where to read next" table in pages/index.adoc if it is a major entry point.

Keeping the docs truthful

Updating the affected page is part of the change, not a follow-up. The mapping:

Change	Page
A new or changed process or task	Process catalog and the relevant process page, plus Domain model: processes & tasks if the framework changed
A new or changed HTTP route	API overview and the matching endpoint page
A new EventBridge event or SWF change	EventBridge events, SWF orchestration
A new table, attribute or S3 path	DynamoDB tables, S3 datalake
A new vendor, AWS or internal client	Component layer and a component page
A new setting or secret	Configuration & secrets, Settings & secrets reference
A build or deploy change	Deployment
A new metric, log or failure mode	Observability, Troubleshooting
A new rule for contributors	Python standards
Any new file worth finding	Source map
A new term	Glossary

Change

Page

A new or changed process or task

Process catalog and the relevant process page, plus Domain model: processes & tasks if the framework changed

A new or changed HTTP route

API overview and the matching endpoint page

A new EventBridge event or SWF change

EventBridge events, SWF orchestration

A new table, attribute or S3 path

DynamoDB tables, S3 datalake

A new vendor, AWS or internal client

Component layer and a component page

A new setting or secret

Configuration & secrets, Settings & secrets reference

A build or deploy change

Deployment

A new metric, log or failure mode

Observability, Troubleshooting

A new rule for contributors

Python standards

Any new file worth finding

Source map

A new term

Glossary

A behaviour change usually touches two or three pages, not one — update the specific page and the summary table or catalog that mentions it.

AGENTS.md at the repository root is the entry point for AI agents and points into this component; keep its doc map in step when you add or remove a page.

The `docs-writer` agent

This repository ships an AI subagent that owns these pages: .claude/agents/docs-writer.md (mirrored in .cursor/agents/). It is invoked after an implementation lands, reads the diff and the touched source files, edits the right pages, and verifies the component still builds warning-free.

Two things to know if you work with it:

It is docs-only. It never edits application code, tests or config. If the code is wrong, it reports that instead of documenting around it.
It encodes the conventions on this page. When you change a convention here — a new attribute in antora.yml, a different diagram approach, a new page area — update the agent definition too, in both .claude/agents/ and .cursor/agents/, or the two will drift.

The wider agent chain (feature-planner → plan-reviewer → feature-executor → execution-validator → docs-writer) is described in AGENTS.md.