Writing these docs

docs/ is an Antora documentation component, not a standalone site. It has no playbook of its own: the central documentation project consumes it as a content source and builds it alongside other components.

Consuming this component

Add the repository to the central playbook’s content sources:

content:
  sources:
    - url: https://github.com/<org>/agentcore.git
      branches: [main]
      start_path: docs

start_path: docs is what makes Antora find docs/antora.yml.

Component descriptor

docs/antora.yml:

Key Value

name

morpheus — the component name used in every cross-component xref

title

Morpheus — display name in the component selector

version

~ — unversioned; pages resolve without a version segment in the URL

start_page

ROOT:index.adoc

nav

One entry per module nav file, in menu order

asciidoc.attributes

Shared facts (account, region, stack names, tenant id, BigQuery project) so a value is written once

Referencing this component from another one:

xref:morpheus:ROOT:index.adoc[Morpheus]
xref:morpheus:business:re-engagement.adoc[Re-engagement segments]

Modules

Module Scope

ROOT

Platform-wide: architecture, configuration, development, deployment, operations, security, conventions

business

Domain rules — what the platform decides and why

agentcore

The Bedrock AgentCore container runtime

lambdas

One page per Lambda function

events

Event catalog, payload schemas, routing

libs

Shared library reference

data

Domain model, ORM, repositories, BigQuery

infrastructure

CDK, SAM, queues, schedules, IAM, observability

plans

Forward-looking design documents

Standard module layout:

modules/<name>/
├── nav.adoc          navigation fragment listed in antora.yml
├── pages/            .adoc pages — one URL each
├── partials/         reusable fragments, included with include::partial$…[]
├── examples/         verbatim files, included with include::example$…[]
├── images/           referenced with image::…[]
└── attachments/      downloadable files, linked with xref:attachment$…[]

Authoring rules

Pages are AsciiDoc

Antora does not build Markdown. Every page is .adoc with a level-0 title (= Title) and section levels stepping down by one.

Every page carries a description
= Page title
:description: One sentence, used for search results and metadata.
Cross-references use resource ids, never file paths
xref:architecture.adoc[System architecture]            (1)
xref:business:re-engagement.adoc[Re-engagement]        (2)
xref:business:call-lists.adoc#suppression[Suppression] (3)
1 Same module.
2 Another module in this component.
3 A section anchor in another module’s page.
Anchors are explicit when linked to

idprefix/idseparator are set, so headings get predictable ids, but any heading that is an xref target should declare its own anchor:

[#suppression]
== Suppression rules
Diagrams are Mermaid in a [mermaid] literal block
 
[mermaid]
....
flowchart LR
  A --> B
....

+ With asciidoctor-kroki registered in the playbook these render as diagrams; without it they degrade to readable literal text. Register the extension in the playbook to get rendered output:

+

asciidoc:
  extensions:
    - asciidoctor-kroki
Shared facts come from attributes

Write us-east-1, morpheus-sam, b191a905-5d19-4fa0-941b-d8eb81c0c477, bigqueryexport-183608 rather than literals. In a code block, opt in to substitution:

[source,bash,subs=attributes+]
----
aws logs tail /aws/lambda/{sam-stack}-hubspot-sync --follow
----
Code references point at real paths

Name the file so a reader can open it — lambdas/morpheus_hubspot/registry.py, libs/morpheus-llm/morpheus_llm/providers/claude_service.py. Do not paste large verbatim blocks that will drift; quote the few lines that carry the rule.

Admonitions carry weight

NOTE for context, TIP for a shortcut, IMPORTANT for something easy to get wrong, WARNING for a rule with consequences, CAUTION for a destructive action. Use them sparingly enough that they still register.

Adding a page

  1. Create modules/<module>/pages/<name>.adoc with a title and :description:.

  2. Add an xref: line to that module’s nav.adoc in the right place.

  3. Cross-link it from any page whose reader would want it.

Adding a whole module also requires appending its nav.adoc to the nav: list in docs/antora.yml, or nothing in it will appear in the menu.

Keeping docs true

The pages describing behaviour — every page under business, events, and lambdas — were written against the source. When you change a rule, change the page in the same pull request. The highest-risk drift points:

If you change… Also update

A registry.py entry

Event catalog

A Pydantic event model in morpheus_common/events/

The matching queue page under events

A schedule or Input in lambdas/template.yaml

EventBridge schedules and Scheduled events

A priority formula in bigquery/*.sql

Re-engagement segments and Daily call lists

A constant in a utils/constants.py

The relevant business page

A secret key or environment variable

Configuration and secrets

An ORM model or repository

ORM models / Repositories