CR-2026-04-11: Codex Granular Page Architecture

Change Request

Field	Value
CR ID	CR-2026-04-11
Author	Evan Rosado
Priority	P2
Status	Approved — not yet started
Category	Documentation Architecture
Scope	All 42 codex categories
Prerequisite	CR-2026-04-10 (STD-016 formatting) should be complete first

Field

Value

CR ID

CR-2026-04-11

Author

Evan Rosado

Priority

Status

Approved — not yet started

Codex tools that grow beyond a few patterns hit a wall. A single grep.adoc page that includes 7 example files becomes a scroll-heavy monolith. There’s no way to navigate directly to "PCRE patterns" vs "infrastructure grep" without scrolling through everything in between.

The three-layer architecture (pages → partials → examples) exists but isn’t applied consistently. Some categories (bash) have granular pages per concern. Others (text, git, networking) have one page per tool with all content flattened.

Objective

Refactor codex tools into per-concern pages backed by partials. Pages are the frontend (thin shells with includes). Partials are the backend (content that grows). As a tool accumulates patterns, new partials are created and new pages expose them. The page never gets cluttered.

Current State vs Target

Current (grep as example)

pages/codex/text/grep.adoc          # One page, 7 includes, growing
partials/codex/text/grep-quick-reference.adoc   # One monolithic partial
examples/codex/text/grep.adoc                   # One example file
examples/codex/grep/pcre-lookaround.adoc        # Split examples
examples/codex/grep/infrastructure-patterns.adoc
examples/codex/grep/pipeline-combinations.adoc
examples/codex/grep/gotchas.adoc

Target

pages/codex/grep/
├── index.adoc              # Overview + xref table to subtopics
├── basics.adoc             # → include::partial$codex/grep/basics-quick-reference.adoc[]
├── pcre.adoc               # → include::partial$codex/grep/pcre-quick-reference.adoc[]
├── infrastructure.adoc     # → include::partial$codex/grep/infrastructure-quick-reference.adoc[]
├── pipelines.adoc          # → include::partial$codex/grep/pipeline-quick-reference.adoc[]
└── gotchas.adoc            # → include::partial$codex/grep/gotchas-quick-reference.adoc[]

partials/codex/grep/
├── basics-quick-reference.adoc
├── pcre-quick-reference.adoc
├── infrastructure-quick-reference.adoc
├── pipeline-quick-reference.adoc
└── gotchas-quick-reference.adoc

examples/codex/grep/
├── pcre-lookaround.adoc
├── recursive-patterns.adoc
├── infrastructure-patterns.adoc
├── pipeline-combinations.adoc
└── gotchas.adoc

Pattern

Layer Role

Layer	Role
Page (frontend)	Thin shell: title, description, navtitle, `include::partial$…[]`. No content in the page itself.
Partial (backend)	The actual content — prose, tables, examples. Grows over time. STD-016 format.
Example (code blocks)	Extracted code blocks >10 lines. Included by partials via `include::example$…[]`.

Page (frontend)

Thin shell: title, description, navtitle, include::partial$…[]. No content in the page itself.

Partial (backend)

The actual content — prose, tables, examples. Grows over time. STD-016 format.

Example (code blocks)

Extracted code blocks >10 lines. Included by partials via include::example$…[].

A page is always:

= grep — PCRE Patterns
:description: Lookaheads, lookbehinds, named groups, non-greedy matching
:navtitle: PCRE

include::partial$codex/grep/pcre-quick-reference.adoc[]

The partial is where content lives and grows. The page never changes unless the title or description changes.

Scope

Phase 1: Promoted Tools (highest traffic, most growth)

Tools currently under codex/text/ that deserve their own top-level category with per-concern pages:

Tool Current Proposed Pages

Tool	Current	Proposed Pages
grep	`text/grep.adoc` (1 page)	`grep/` — basics, pcre, infrastructure, pipelines, gotchas
awk	`text/awk.adoc` + awk-advanced + awk-logs + awk-network (4 pages under text/)	`awk/` — basics, field-extraction, state-machines, logs, network, one-liners
sed	`text/sed.adoc` (1 page)	`sed/` — basics, in-place, addresses, hold-buffer, recipes
find	`text/find.adoc` (1 page)	`find/` — basics, exec, time-size, pruning, xargs-integration
jq	`text/jq.adoc` (1 page)	`jq/` — basics, filters, transforms, api-patterns, sysadmin

grep

text/grep.adoc (1 page)

grep/ — basics, pcre, infrastructure, pipelines, gotchas

awk

text/awk.adoc + awk-advanced + awk-logs + awk-network (4 pages under text/)

awk/ — basics, field-extraction, state-machines, logs, network, one-liners

sed

text/sed.adoc (1 page)

sed/ — basics, in-place, addresses, hold-buffer, recipes

find

text/find.adoc (1 page)

find/ — basics, exec, time-size, pruning, xargs-integration

text/jq.adoc (1 page)

jq/ — basics, filters, transforms, api-patterns, sysadmin

Phase 2: Other Growing Tools

Category Candidates for splitting

Category	Candidates for splitting
git	Already has some granularity, but `remotes.adoc` and `hooks.adoc` could split further
networking	`curl.adoc`, `ssh.adoc` — each has enough patterns for per-concern pages
linux	`systemd.adoc`, `networking.adoc` — broad topics that benefit from splitting
security	`certificates.adoc` — could split into x509, openssl, vault-pki

git

Already has some granularity, but remotes.adoc and hooks.adoc could split further

networking

curl.adoc, ssh.adoc — each has enough patterns for per-concern pages

linux

systemd.adoc, networking.adoc — broad topics that benefit from splitting

security

certificates.adoc — could split into x509, openssl, vault-pki

Phase 3: Remaining Categories

Apply the pattern to any category that has >5 concerns in a single partial.

Nav Impact

Each promoted tool gets its own nav section:

*** grep
**** xref:codex/grep/index.adoc[Overview]
**** xref:codex/grep/basics.adoc[Basics]
**** xref:codex/grep/pcre.adoc[PCRE]
**** xref:codex/grep/infrastructure.adoc[Infrastructure]
**** xref:codex/grep/pipelines.adoc[Pipelines]
**** xref:codex/grep/gotchas.adoc[Gotchas]

The text/ category index page updates to reference the promoted tools by their new paths, and retains the simpler tools (cut, sort, tr, wc, uniq, paste, comm, column) that don’t need splitting.

Constraints

STD-016 format inside every partial — .Title blocks, [source,bash], tested commands
No content in pages — pages are includes only
Existing xrefs to codex/text/grep.adoc must redirect or be updated
CR-2026-04-10 (formatting refactor) should complete before this starts to avoid conflicts
One tool at a time — don’t bulk-refactor. Validate each before moving to the next.