Terminal Operations — Read, Search, Edit, Add, Verify

Man Page References

Every command below traces to a manual section. Use these to go deeper.

Tool Key Section Command

Tool	Key Section	Command
`grep`	Pattern matching, `-r` recursive, `-P` PCRE, `-o` only-matching, `-l` files-only	`man grep` → REGULAR EXPRESSIONS
`find`	`-type f`, `-name`, `-mtime`, `-size`, `-exec`	`man find` → EXPRESSIONS
`awk`	Pattern ranges (`/start/,/end/`), field extraction, `BEGIN`/`END`, `NR`	`man awk` → PATTERNS (or `info gawk`)
`sed`	In-place `-i`, line addressing, substitute `s///`, insert `i\`, append `a\`	`man sed` → ADDRESSES, `info sed` → "sed scripts"
`wc`	`-l` lines, `-w` words, `-c` bytes	`man wc`
`diff`	Unified format, process substitution input `<()`	`man diff` → OUTPUT FORMATS
`cat`	`-n` line numbers, heredoc input `<< 'EOF'`	`man cat`, `man bash` → HERE DOCUMENTS
`jq`	`group_by`, `map`, `select`, `@tsv`, `-r` raw output	`man jq` → BUILTIN OPERATORS
`xargs`	`-I{}` placeholder, `-exec` vs pipe, `-0` null-delimited	`man xargs`
`tee`	Split stdout to file + terminal simultaneously	`man tee`

grep

Pattern matching, -r recursive, -P PCRE, -o only-matching, -l files-only

man grep → REGULAR EXPRESSIONS

find

-type f, -name, -mtime, -size, -exec

man find → EXPRESSIONS

awk

Pattern ranges (/start/,/end/), field extraction, BEGIN/END, NR

man awk → PATTERNS (or info gawk)

sed

In-place -i, line addressing, substitute s///, insert i\, append a\

man sed → ADDRESSES, info sed → "sed scripts"

wc

-l lines, -w words, -c bytes

man wc

diff

Unified format, process substitution input <()

man diff → OUTPUT FORMATS

cat

-n line numbers, heredoc input << 'EOF'

man cat, man bash → HERE DOCUMENTS

jq

group_by, map, select, @tsv, -r raw output

man jq → BUILTIN OPERATORS

xargs

-I{} placeholder, -exec vs pipe, -0 null-delimited

man xargs

tee

Split stdout to file + terminal simultaneously

man tee

bash substitution order — man bash → EXPANSION

1. Brace expansion          {a,b,c}        man bash → Brace Expansion
2. Tilde expansion           ~              man bash → Tilde Expansion
3. Parameter expansion       ${var}         man bash → Parameter Expansion
4. Command substitution      $(cmd)         man bash → Command Substitution
5. Arithmetic expansion      $(( ))         man bash → Arithmetic Expansion
6. Process substitution      <(cmd)         man bash → Process Substitution
7. Word splitting            unquoted $var  man bash → Word Splitting
8. Filename expansion        *.adoc         man bash → Pathname Expansion

Navigation — Where Things Live

path resolution cheat sheet

pages/       → container shells (include directives only)
partials/    → actual content (this is what you edit)
examples/    → code snippets (include::example$)
nav.adoc     → navigation tree
antora.yml   → attributes (single source of truth)

partial$ = docs/modules/ROOT/partials/
example$ = docs/modules/ROOT/examples/

resolve an include path to a real file

# include::partial$projects/murus-portae/summary.adoc[]
# becomes:
bat docs/modules/ROOT/partials/projects/murus-portae/summary.adoc

resolve ALL includes in any page — man grep → -o only-matching, -P PCRE, \K reset match start

PAGE="docs/modules/ROOT/pages/projects/personal/domus-asciidoc-build/index.adoc"
grep -oP 'include::partial\$\K[^\[]+' "$PAGE" | \
  while read -r inc; do
    f="docs/modules/ROOT/partials/${inc}"
    [ -f "$f" ] && printf "─── %s ───\n" "$inc" && cat "$f" && echo ""
  done

verified output (2026-04-21)

─── projects/domus-asciidoc-build/summary.adoc ───
─── projects/domus-asciidoc-build/purpose.adoc ───
─── projects/domus-asciidoc-build/metadata.adoc ───

find every page that uses a specific partial

grep -rl 'partial\$projects/murus-portae/' docs/modules/ROOT/pages/

follow the include chain: page → partial → sub-partial

# Level 1: what does the page include?
grep 'include::' docs/modules/ROOT/pages/2026/04/WRKLOG-2026-04-21.adoc

# Level 2: what does that partial include?
grep 'include::' docs/modules/ROOT/partials/worklog/urgent.adoc

# Level 3: deeper
grep 'include::' docs/modules/ROOT/partials/worklog/urgent/professional.adoc

Worklog Patterns — Date-Driven Access

Path structure: pages/YYYY/MM/WRKLOG-YYYY-MM-DD.adoc — date components are shell-addressable.

Single Worklog

today — command substitution builds the date — man bash → Command Substitution

bat docs/modules/ROOT/pages/2026/$(date +%m)/WRKLOG-$(date +%Y-%m-%d).adoc

specific date — just type it

bat docs/modules/ROOT/pages/2026/04/WRKLOG-2026-04-17.adoc

headings only (outline) — man awk → PATTERNS

awk '/^=+ /' docs/modules/ROOT/pages/2026/$(date +%m)/WRKLOG-$(date +%Y-%m-%d).adoc

carryover section only — man awk → pattern range /start/,/end/

awk '/^=== Carryover/,/^include::/' docs/modules/ROOT/pages/2026/04/WRKLOG-2026-04-21.adoc

open items only — man grep → REGULAR EXPRESSIONS

grep '\[ \]' docs/modules/ROOT/pages/2026/$(date +%m)/WRKLOG-$(date +%Y-%m-%d).adoc

open vs done count — man awk → variables, END block

awk '/\[ \]/{o++} /\[x\]/{d++} END{printf "Open: %d  Done: %d\n",o,d}' \
  docs/modules/ROOT/pages/2026/$(date +%m)/WRKLOG-$(date +%Y-%m-%d).adoc

Multiple Worklogs — Brace Expansion

this week — man bash → Brace Expansion

bat docs/modules/ROOT/pages/2026/04/WRKLOG-2026-04-{17,18,19,20,21}.adoc

headings across a range

for f in docs/modules/ROOT/pages/2026/04/WRKLOG-2026-04-{17,18,19,20,21}.adoc; do
  printf "\n═══ %s ═══\n" "${f##*/}"
  awk '/^=+ /' "$f"
done

open item count per day (trend) — brace expansion + command substitution

grep -c '\[ \]' docs/modules/ROOT/pages/2026/04/WRKLOG-2026-04-{17,18,19,20,21}.adoc

verified output (2026-04-21)

docs/modules/ROOT/pages/2026/04/WRKLOG-2026-04-17.adoc:34
docs/modules/ROOT/pages/2026/04/WRKLOG-2026-04-18.adoc:27
docs/modules/ROOT/pages/2026/04/WRKLOG-2026-04-19.adoc:18
docs/modules/ROOT/pages/2026/04/WRKLOG-2026-04-20.adoc:30
docs/modules/ROOT/pages/2026/04/WRKLOG-2026-04-21.adoc:43

Worklog Search — Glob Expansion

all April worklogs — man bash → Pathname Expansion

ls -1 docs/modules/ROOT/pages/2026/04/WRKLOG-*.adoc

search all worklogs for a topic — man grep → -r recursive, -l files-only

grep -l 'murus-portae' docs/modules/ROOT/pages/2026/04/WRKLOG-*.adoc

what day did I work on MSCHAPv2?

grep -l 'MSCHAPv2' docs/modules/ROOT/pages/2026/04/WRKLOG-*.adoc

search across ALL months

grep -rl 'mandiant' docs/modules/ROOT/pages/2026/*/WRKLOG-*.adoc

Worklog Diffs — Process Substitution

what items were ADDED today vs yesterday — man bash → Process Substitution, man diff

diff <(grep '\[ \]' docs/modules/ROOT/pages/2026/04/WRKLOG-2026-04-20.adoc | sort) \
     <(grep '\[ \]' docs/modules/ROOT/pages/2026/04/WRKLOG-2026-04-21.adoc | sort)

what items were COMPLETED today vs yesterday

diff <(grep '\[x\]' docs/modules/ROOT/pages/2026/04/WRKLOG-2026-04-20.adoc | sort) \
     <(grep '\[x\]' docs/modules/ROOT/pages/2026/04/WRKLOG-2026-04-21.adoc | sort) | grep '^>'

Substitutions Used in Worklog Patterns

Pattern Substitution Type man bash Section

Pattern	Substitution Type	`man bash` Section
`$(date +%m)`	Command substitution	Command Substitution
`{17,18,19,20,21}`	Brace expansion	Brace Expansion
`WRKLOG-*.adoc`	Filename/glob expansion	Pathname Expansion
`${f##*/}`	Parameter expansion (strip path)	Parameter Expansion
`<(grep …)`	Process substitution	Process Substitution

$(date +%m)

Command substitution

Command Substitution

{17,18,19,20,21}

Brace expansion

Brace Expansion

WRKLOG-*.adoc

Filename/glob expansion

Pathname Expansion

${f##*/}

Parameter expansion (strip path)

Parameter Expansion

<(grep …)

Process substitution

Process Substitution

Finding Things in Your Own Codex

When you know the topic but not the file.

search codex file names — man find → -type f, -name

find docs/modules/ROOT/partials/codex/bash -type f -name '*test*'

dump first line of every codex entry in a category — man awk → FNR (resets per file)

awk 'FNR==1' docs/modules/ROOT/partials/codex/bash/*.adoc

search codex content for a keyword — man grep → -rli (recursive, files-only, case-insensitive)

grep -rli 'conditional' docs/modules/ROOT/partials/codex/bash/

search ALL codex categories

grep -rl 'strace' docs/modules/ROOT/partials/codex/

list all codex categories — man find → -maxdepth 1

find docs/modules/ROOT/partials/codex -maxdepth 1 -type d

scan headings across a category — man awk → FNR, /^=+ /

for f in docs/modules/ROOT/partials/codex/bash/*.adoc; do
  printf "\n═══ %s ═══\n" "${f##*/}"
  awk '/^=+ /' "$f"
done

Read Operations

Single File

read a partial

bat docs/modules/ROOT/partials/projects/murus-portae/summary.adoc

read with line numbers (for sed targeting)

cat -n docs/modules/ROOT/partials/projects/murus-portae/appendix-todos.adoc

read a specific line range

awk 'NR>=10 && NR<=25' docs/modules/ROOT/partials/projects/murus-portae/summary.adoc

extract just the section headings (document outline) — man awk → PATTERNS

awk '/^=+ /' docs/modules/ROOT/pages/2026/04/WRKLOG-2026-04-21.adoc

verified output (2026-04-21)

= WRKLOG-2026-04-21
== Summary
== Session Accomplishments (Claude Code)
=== Worklog Catch-Up
=== PRJ-domus-asciidoc-build — Restructured to STD-001
== Today's Priorities
=== P0 — Must Do Today
==== CAB Presentation — 15:00
==== MSCHAPv2 — Schedule Wednesday Meeting
==== SIEM Migration — Report Ready
==== Mandiant Remediation
==== ISE Security
=== P0 — Active (No Fixed Deadline)
=== P1 — Important
=== Administrative
=== Active Project Portfolio (d001 — 14 projects)
=== Infrastructure — Open
=== Personal — Carried

Bulk Read

read all project summaries

for f in docs/modules/ROOT/partials/projects/*/summary.adoc; do
  slug="${f%/*}"; slug="${slug##*/}"
  printf "\n═══ %s ═══\n" "$slug"
  cat "$f"
done | less

read all appendix-todos across projects

for f in docs/modules/ROOT/partials/projects/*/appendix-todos.adoc; do
  slug="${f%/*}"; slug="${slug##*/}"
  printf "\n═══ %s ═══\n" "$slug"
  cat "$f"
done | less

Table Extraction

extract table rows from an AsciiDoc table — man awk → pattern {action} and toggle variable

awk '/^\|===/{p=!p; next} p' docs/modules/ROOT/partials/projects/murus-portae/metadata.adoc

verified output (2026-04-21)

| Field | Value

| PRJ ID | PRJ-2026-04-murus-portae
| Author | {author}
| Created | 2026-04-15
| Updated | 2026-04-16
| Status | Active — discovery phase
| Category | Network Security / Application Security
| Priority | P0 (management request)
| Scope | Layer 7 WAF readiness assessment and implementation
| Platforms | Citrix NetScaler (reverse proxy), Cisco FTD/FMC (perimeter firewall)
| Related | PRJ-2026-04-firewall-audit, PRJ-2026-04-dmz-migration

extract a named section (from heading to next heading)

awk '/^== Status/{p=1} p && /^== / && !/Status/{exit}' docs/modules/ROOT/partials/projects/domus-asciidoc-build/status.adoc

Search Operations

By Content

find files containing a term

grep -rli 'mandiant' docs/modules/ROOT/

find with context (3 lines around match)

grep -rn -C3 'BLOCKED' docs/modules/ROOT/partials/projects/*/summary.adoc

find with PCRE regex — MAC addresses

grep -rPl '[0-9A-F]{2}(:[0-9A-F]{2}){5}' docs/modules/ROOT/

find hardcoded IPs (STD-004 violation)

grep -rPn '(?<!\{)\b10\.50\.\d+\.\d+\b(?!\})' docs/modules/ROOT/partials/

find all xrefs in a file

grep -oP 'xref:[^\[]+' docs/modules/ROOT/pages/2026/04/WRKLOG-2026-04-21.adoc

find status markers across all projects — man grep → -h suppress filename, -o only-matching, -P PCRE

grep -rhoP '(Active|BLOCKED|Behind|Draft|Operational|Planned)' docs/modules/ROOT/partials/projects/*/summary.adoc | sort | uniq -c | sort -rn

verified output (2026-04-21)

     54 Active
      8 Planned
      4 Operational
      1 Draft
      1 BLOCKED

By File

find files by name pattern — man find → TESTS → -name, -type

find docs/modules/ROOT -type f -name '*murus*'
find docs/modules/ROOT/partials/projects -type f -name 'summary.adoc'

find files modified today — man find → TESTS → -mtime

find docs/modules/ROOT -type f -name '*.adoc' -mtime 0

find files modified in last 3 days — -mtime -3 means "less than 3 days ago"

find docs/modules/ROOT -type f -name '*.adoc' -mtime -3

find large files (>50KB — may need splitting per STD-001) — man find → -size

find docs/modules/ROOT -type f -name '*.adoc' -size +50k -exec ls -lh {} \;

find encrypted files with plaintext copies (security audit) — man find → -exec with sh -c

# Uses parameter expansion ${1%.age} to strip .age suffix
# man bash → Parameter Expansion → ${parameter%word}
find data/ -name '*.adoc.age' -exec sh -c 'plain="${1%.age}"; [ -f "$plain" ] && echo "PLAINTEXT: $plain"' _ {} \;

Edit Operations

Field Updates (sed)

update revdate

# Before
awk '/:revdate:/' docs/modules/ROOT/pages/projects/personal/domus-asciidoc-build/index.adoc

# Change
sed -i 's/:revdate: 2026-04-19/:revdate: 2026-04-21/' docs/modules/ROOT/pages/projects/personal/domus-asciidoc-build/index.adoc

# After
awk '/:revdate:/' docs/modules/ROOT/pages/projects/personal/domus-asciidoc-build/index.adoc

update status in metadata table

sed -i 's/| Active/| Operational/' docs/modules/ROOT/partials/projects/domus-asciidoc-build/metadata.adoc

update Last Updated date (awk — safer for table rows)

awk '/Last Updated/{sub(/2026-04-19/, "2026-04-21")}1' \
  docs/modules/ROOT/partials/projects/domus-asciidoc-build/metadata.adoc > /tmp/m && \
  mv /tmp/m docs/modules/ROOT/partials/projects/domus-asciidoc-build/metadata.adoc

mark a checkbox as done — man sed → ADDRESSES (line number), man grep → -n line numbers

# Find the line number first
grep -n 'Schedule recurring Wednesday' docs/modules/ROOT/partials/trackers/work/priorities/current.adoc

# Mark it done (replace [ ] with [x] on that specific line)
sed -i '19s/\[ \]/[x]/' docs/modules/ROOT/partials/trackers/work/priorities/current.adoc

# Verify
awk 'NR==19' docs/modules/ROOT/partials/trackers/work/priorities/current.adoc

Bulk Edits

update a date across all project metadata files

find docs/modules/ROOT/partials/projects -name 'metadata.adoc' -exec \
  sed -i 's/Next Review: 2026-04-08/Next Review: 2026-05-08/' {} \;

rename an attribute across all files

grep -rl '{old-attribute}' docs/modules/ROOT/ | xargs sed -i 's/{old-attribute}/{new-attribute}/g'

Add Operations

Append to Existing Files

append a TODO row to a project (before closing |===)

sed -i '/^|===$/ i\
| P2\
| New task description here\
| Pending' docs/modules/ROOT/partials/projects/domus-asciidoc-build/appendix-todos.adoc

append an include to a page (before == Related)

sed -i '/^== Related/i include::partial$projects/domus-asciidoc-build/appendix-lessons.adoc[]\n' \
  docs/modules/ROOT/pages/projects/personal/domus-asciidoc-build/index.adoc

append a checklist item to priorities

sed -i '/^=== P1/i * [ ] **P0** - New urgent item description' \
  docs/modules/ROOT/partials/trackers/work/priorities/current.adoc

Create New Files

create a new partial from heredoc

cat > docs/modules/ROOT/partials/projects/domus-asciidoc-build/appendix-lessons.adoc << 'EOF'
// Partial: Lessons for domus-asciidoc-build

== Lessons Learned

* Antora `partial$` resolves to module-relative paths
* `border-separate` gives carved grid tables across all CSS variants
* Theme as parameter (`--theme`) not hardcoded = reusable
EOF

create a new container page (6-line shell template)

SLUG="domus-asciidoc-build"
TITLE="Lessons Learned"
NAVTITLE="Lessons"
TARGET="docs/modules/ROOT/pages/projects/personal/${SLUG}/appendix-lessons.adoc"

cat > "$TARGET" << EOF
= ${TITLE}
:description: ${SLUG} lessons learned
:navtitle: ${NAVTITLE}
:icons: font

include++::++partial$projects/${SLUG}/appendix-lessons.adoc[]
EOF

scaffold a full new project (STD-001 compliant)

SLUG="bibliotheca"
CATEGORY="personal"
TITLE="Domus Library System"
PRJ_ID="PRJ-2026-04-bibliotheca"
BASE_PARTIAL="docs/modules/ROOT/partials/projects/${SLUG}"
BASE_PAGE="docs/modules/ROOT/pages/projects/${CATEGORY}/${SLUG}"

mkdir -p "$BASE_PARTIAL" "$BASE_PAGE"

# metadata.adoc
cat > "${BASE_PARTIAL}/metadata.adoc" << EOF
// Partial: Metadata for ${SLUG}

== Metadata

[cols="1,2"]
|===
| Field | Value

| PRJ ID | ${PRJ_ID}
| Author | {author}
| Created | $(date +%Y-%m-%d)
| Last Updated | $(date +%Y-%m-%d)
| Status | Active
| Next Review | $(date -d '+30 days' +%Y-%m-%d)
|===
EOF

# summary.adoc
cat > "${BASE_PARTIAL}/summary.adoc" << EOF
// Partial: Summary for ${SLUG}

== Summary

${TITLE} — overview here.
EOF

# appendix-todos.adoc
cat > "${BASE_PARTIAL}/appendix-todos.adoc" << 'EOF'
// Partial: TODOs

== TODOs

[cols="1,3,1"]
|===
| Priority | Task | Status

| P1
| Initial task
| Pending
|===
EOF

# appendix-issues.adoc
cat > "${BASE_PARTIAL}/appendix-issues.adoc" << 'EOF'
// Partial: Known Issues

== Known Issues

No known issues.
EOF

# index.adoc (container page)
cat > "${BASE_PAGE}/index.adoc" << EOF
= ${TITLE}
:description: ${TITLE}
:navtitle: Overview
:icons: font

include++::++partial$projects/${SLUG}/summary.adoc[]

include++::++partial$projects/${SLUG}/metadata.adoc[]
EOF

# appendix pages
for appendix in appendix-todos appendix-issues; do
  cat > "${BASE_PAGE}/${appendix}.adoc" << EOF
= ${appendix##appendix-}
:description: ${SLUG} ${appendix##appendix-}
:navtitle: ${appendix##appendix-}
:icons: font

include++::++partial$projects/${SLUG}/${appendix}.adoc[]
EOF
done

echo "Scaffolded: ${SLUG}"
ls -1 "${BASE_PARTIAL}/" "${BASE_PAGE}/"

Verify Operations

verify-before / change / verify-after pattern (STD-008)

# Before
awk '/Status/' docs/modules/ROOT/partials/projects/domus-asciidoc-build/metadata.adoc

# Change
sed -i 's/| Active/| Operational/' docs/modules/ROOT/partials/projects/domus-asciidoc-build/metadata.adoc

# After
awk '/Status/' docs/modules/ROOT/partials/projects/domus-asciidoc-build/metadata.adoc

verify no hardcoded IPs after editing

grep -Pn '\b10\.50\.\d+\.\d+\b' docs/modules/ROOT/partials/projects/domus-asciidoc-build/*.adoc

verify no :toc: in any file

grep -rn ':toc:' docs/modules/ROOT/pages/projects/personal/domus-asciidoc-build/

verify build after changes

make 2>&1 | grep -E "WARN|ERROR"

Analytics — Dashboards from the Terminal

project status dashboard — man bash → Parameter Expansion ${var%/} ${var##/}, man grep → -P lookbehind

# ${d%/*}  = strip shortest suffix matching /* (removes filename)
# ${slug##*/} = strip longest prefix matching */ (removes path, keeps slug)
# grep -oP '(?<=...)' = PCRE lookbehind — match text AFTER "Status | "
for d in docs/modules/ROOT/partials/projects/*/summary.adoc; do
  slug="${d%/*}"; slug="${slug##*/}"
  status=$(grep -oP '(?<=Status\s*\|\s).*' "$d" 2>/dev/null | head -1)
  printf "%-35s %s\n" "$slug" "${status:-unknown}"
done | sort -k2

open item count per worklog (trend)

for f in docs/modules/ROOT/pages/2026/04/WRKLOG-2026-04-{17,18,19,20,21}.adoc; do
  count=$(grep -c '\[ \]' "$f" 2>/dev/null || echo 0)
  printf "%s  %3d open  %s\n" "${f##*/}" "$count" "$(printf '█%.0s' $(seq 1 $((count/3))))"
done

delta: new items added between worklogs

diff <(grep '\[ \]' docs/modules/ROOT/pages/2026/04/WRKLOG-2026-04-20.adoc | sort) \
     <(grep '\[ \]' docs/modules/ROOT/pages/2026/04/WRKLOG-2026-04-21.adoc | sort) | grep '^>'

commit velocity sparkline

for day in {07..21}; do
  date="2026-04-${day}"
  count=$(grep -c "^${date}" data/d000/infra/cross-repo-activity-2026-04-07-to-2026-04-21.adoc 2>/dev/null || echo 0)
  printf "%s  %3d  %s\n" "$date" "$count" "$(printf '█%.0s' $(seq 1 $((count/2))))"
done

MSCHAPv2 ownership matrix — quick pull

awk '/platform ownership/,/Enterprise Linux/' docs/modules/ROOT/partials/trackers/work/priorities/current.adoc

all people mentioned in priorities

grep -oP '(Tony|Mark|Argam|Drew|Andrew|Jason|Victor|Justin|Arin|David|Shahab|Ding)\s*\w*' \
  docs/modules/ROOT/partials/trackers/work/priorities/current.adoc | sort -u