STD-016: Codex Entry Format

The standard format for Codex entries — the tactical CLI reference library ("The Arsenal"). 77+ pages across 15 categories. Each entry is a reference card: terse, scannable, code-heavy. Narrative belongs in worklogs and pattern journals. Extracted from codex audit (Apr 2026).

Principles

  1. Reference, not narrative. A codex entry answers "how does this work?" with examples. It does not tell a story. That is what pattern journals do.

  2. Code lives in examples/. Inline code blocks exceeding 10 lines are extracted to examples/codex/<category>/ and included. No exceptions.

  3. Categories are self-contained. A reader should not need to leave the category to understand the entry. Cross-references enhance; they do not complete.

  4. Density over length. A good codex entry is a cheat sheet. If it exceeds 300 lines, it should be split into multiple entries within the same category.

  5. Every entry earns its place. If a command or technique does not warrant a reference card, it belongs in a worklog quick-commands section or a pattern journal entry — not the codex.

Categories

The codex is organized into 37 categories (expanded Apr 2026 from 15). New categories require justification (distinct tool domain, 3+ planned entries).

Category Scope

text

awk, sed, grep, regex, text processing pipelines

bash

Shell scripting, builtins, parameter expansion, process management

vim

Neovim motions, commands, registers, macros, plugin usage

git

Version control, branching, rebasing, bisect, reflog

linux

System administration, systemd, filesystems, package management

networking

TCP/IP, DNS, firewall rules, packet capture, routing

powershell

Windows automation, AD cmdlets, ISE scripting

python

Standard library, data structures, idioms, debugging

security

Cryptography, certificates, hardening, audit tools

containers

Docker, Podman, compose, image management

gopass

Password store, secret management, team sharing

assembly

x86/ARM instructions, registers, calling conventions

iac

Terraform, Ansible, infrastructure patterns

languages

Polyglot reference (Lua, Go, Rust, etc.)

kql

Kusto Query Language for log analytics

cisco

IOS-XE, NX-OS, ISE, WLC, ASA, FMC, DNAC, dot1x, RADIUS

dns

BIND, zones, DNSSEC, split-horizon, dig, nslookup

apis

REST, GraphQL, gRPC, OpenAPI, authentication, pagination

databases

SQL, PostgreSQL, Redis, MongoDB, queries, migrations

json-yaml

jq, yq, JSON Schema, YAML anchors, TOML, CSV processing

web

HTTP protocol, OAuth2, JWT, CORS, WebSockets, TLS

ai

Claude Code, Ollama, prompting, RAG, embeddings, agents

automation

cron, systemd timers, webhooks, CI/CD, GitHub Actions

secrets

gopass, age, GPG, Vault, SSH keys, YubiKey

documentation

AsciiDoc, Antora, LaTeX, D2, Mermaid, Graphviz

mathematics

algebra, calculus, linear algebra, statistics, graph theory

science

physics, chemistry, cryptography, information theory

music

theory, scales, LilyPond, cello, violin, practice methods

languages

Spanish, Latin, Greek, Hebrew, linguistics

life

financial literacy, time management, learning methods, career

go

structs, interfaces, goroutines, channels, maps, testing

rust

ownership, borrowing, lifetimes, traits, error handling

cpp

pointers, memory, classes, templates, STL

javascript

DOM, fetch, async/await, Node, TypeScript, React

lua

tables, functions, metatables, Neovim API

ruby

blocks, iterators, metaprogramming, DSL

terminal

tmux, screen, kitty, multiplexers, ANSI codes

zsh

completion, plugins, prompts, widgets

fastapi

domus-api patterns, Pydantic, dependency injection
claude and quickref are meta-categories. fastapi includes the domus-api command reference (gold standard implementation).

Requirements

The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" are used per RFC 2119.

  1. Every codex entry MUST include the document header: = Title, :description:, :navtitle:, :icons: font.

  2. Every codex entry MUST begin with a [.lead] paragraph stating the entry’s scope in 1-2 sentences.

  3. Code content exceeding 10 lines MUST be extracted to examples/codex/<category>/ and included via include::example$codex/<category>/<file>.adoc[].

  4. Inline code blocks of 10 lines or fewer MAY remain in the partial directly.

  5. Every category MUST have an index page with a table listing all entries (columns: Page, Focus).

  6. Every codex entry SHOULD include a == See Also section with xrefs to related codex entries and pattern journal pages.

  7. Categories MUST be self-contained — a reader MUST NOT need to leave the category to understand the entry’s core content.

  8. Codex entries MUST NOT duplicate content from pattern journal pages. Codex = "how does this work?" (reference). Patterns = "when I hit X, I solved it with Y" (experiential).

Entry Template

= Entry Title
:description: One-line description of what this entry covers
:navtitle: Short Title
:icons: font

[.lead]
Brief scope statement -- what tool or technique this card covers and when to reach for it.

== Section Heading

Explanation of concept or technique.

include::example$codex/<category>/<example-file>.adoc[]

== Section Heading

Further techniques, grouped by concern.

[cols="1,2,2"]
|===
| Command | Purpose | Example

| `cmd --flag`
| What it does
| `cmd --flag value`
|===

== See Also

* xref:codex/<category>/<related-entry>.adoc[Related Entry] -- why it is related
* xref:patterns/<category>/<pattern>.adoc[Pattern: Title] -- experiential counterpart

Category Index Template

Each category’s index.adoc (the container page) includes a partial that provides the category overview. The partial MUST contain:

[.lead]
One-line description of the category's scope.

[cols="2,3"]
|===
| Page | Focus

| xref:codex/<category>/<entry>.adoc[Entry Title]
| What this entry covers

| xref:codex/<category>/<entry>.adoc[Entry Title]
| What this entry covers
|===

File Layout

pages/codex/<category>/
├── index.adoc              # Category overview (container page)
├── <entry-a>.adoc          # Container page per entry
└── <entry-b>.adoc

partials/codex/<category>/
├── index.adoc              # Category table partial
├── <entry-a>.adoc          # Entry content partial
└── <entry-b>.adoc

examples/codex/<category>/
├── <example-a>.adoc        # Extracted code blocks
└── <example-b>.adoc

Codex vs Pattern Journal

Dimension Codex Pattern Journal

Question answered

"How does this work?"

"When I hit X, I solved it with Y"

Tone

Reference — terse, scannable

Experiential — narrative, contextual

Structure

Tables, code blocks, flags

Problem/solution pairs, session logs

Audience

Future self needing syntax

Future self needing judgment

Location

pages/codex/<category>/

pages/patterns/<category>/

Quick-Reference Partial Format (Gold Standard)

Codex partials in partials/codex/<category>/ MUST follow this format. This is the structure that makes entries queryable via domus-api, readable in Antora, and useful at 2 AM.

Structure

// <category>/<topic> Quick Reference
// Usage: include::partial$codex/<category>/<topic>-quick-reference.adoc[]
// Last updated: YYYY-MM-DD
// Status: POPULATED

== Section Heading (1)

.Description of what this does (2)
[source,bash] (3)
\----
curl -s localhost:8080/search?q=security | jq '[.results[] | {title, component}]'
\----

.Output (4)
[source,json]
\----
[
  {"title": "Security Patterns", "component": "captures"},
  {"title": "EAP-TLS Configuration", "component": "enterprise-linux-8021x"}
]
\----

.Another command with explanation (5)
[source,bash]
\----
curl -s localhost:8080/standards | jq -r '.standards[] | [.id, .status] | @tsv' | column -t
\----

.Output
\----
STD-001  Active
STD-002  Active
\----
1 Group commands by concern (Health, Search, Standards, etc.)
2 .Title block creates a labeled code block — explains why before showing how
3 [source,bash] for commands, [source,json] for JSON output, [source,python] for Python
4 Show real output — not "example output" but actual results from a tested command
5 Every command must be tested against a live system before committing

Rules

  1. Every command MUST be tested before committing. No untested examples.

  2. Output blocks MUST show real data from a live system — not fabricated samples.

  3. Use [source,bash] for commands, [source,json] for JSON, [source,python] for Python, plain ---- for untyped output.

  4. Use .Title blocks (dot-prefixed) to label each command with its purpose.

  5. Group commands under == Section headings by concern.

  6. Include the // Last updated: and // Status: comments in the header.

  7. Status values: SCAFFOLD (empty TODO), POPULATED (has real content), VERIFIED (tested against live system).

Anti-Pattern: Flat Tables

The flat table format ([cols="2,4"] with |command |description) is acceptable for quick-reference summaries but MUST NOT be the only format for command-heavy entries. Rich entries use the gold standard format above — code blocks with output, section headings, labeled examples.

Reference Implementation

partials/codex/fastapi/domus-api-commands.adoc — 60+ tested commands with real output, section hierarchy, multiple source block types. This is the standard all command-heavy codex entries should follow.

Compliance Checklist

# Check Result

1

Document header includes = Title, :description:, :navtitle:, :icons: font

PASS / FAIL

2

Entry begins with [.lead] scope paragraph

PASS / FAIL

3

No inline code blocks exceeding 10 lines — extracted to examples/codex/

PASS / FAIL

4

Category index exists with Page/Focus table

PASS / FAIL

5

Entry does not duplicate pattern journal content

PASS / FAIL

6

No :toc: attributes in any file

PASS / FAIL

Related