diff --git a/docs/diagrams/out/seq-hery-compose-dark.svg b/docs/diagrams/out/seq-hery-compose-dark.svg
new file mode 100644
index 0000000..2cb8692
--- /dev/null
+++ b/docs/diagrams/out/seq-hery-compose-dark.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/diagrams/out/seq-hery-compose.svg b/docs/diagrams/out/seq-hery-compose.svg
new file mode 100644
index 0000000..8957dd0
--- /dev/null
+++ b/docs/diagrams/out/seq-hery-compose.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/diagrams/out/seq-hery-entity-dark.svg b/docs/diagrams/out/seq-hery-entity-dark.svg
new file mode 100644
index 0000000..316e0ec
--- /dev/null
+++ b/docs/diagrams/out/seq-hery-entity-dark.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/diagrams/out/seq-hery-entity-get-dark.svg b/docs/diagrams/out/seq-hery-entity-get-dark.svg
new file mode 100644
index 0000000..ce9f774
--- /dev/null
+++ b/docs/diagrams/out/seq-hery-entity-get-dark.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/diagrams/out/seq-hery-entity-get.svg b/docs/diagrams/out/seq-hery-entity-get.svg
new file mode 100644
index 0000000..3b1783b
--- /dev/null
+++ b/docs/diagrams/out/seq-hery-entity-get.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/diagrams/out/seq-hery-entity-init-dark.svg b/docs/diagrams/out/seq-hery-entity-init-dark.svg
new file mode 100644
index 0000000..b638ebc
--- /dev/null
+++ b/docs/diagrams/out/seq-hery-entity-init-dark.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/diagrams/out/seq-hery-entity-init.svg b/docs/diagrams/out/seq-hery-entity-init.svg
new file mode 100644
index 0000000..9053d67
--- /dev/null
+++ b/docs/diagrams/out/seq-hery-entity-init.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/diagrams/out/seq-hery-entity-list-dark.svg b/docs/diagrams/out/seq-hery-entity-list-dark.svg
new file mode 100644
index 0000000..e9fca76
--- /dev/null
+++ b/docs/diagrams/out/seq-hery-entity-list-dark.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/diagrams/out/seq-hery-entity-list.svg b/docs/diagrams/out/seq-hery-entity-list.svg
new file mode 100644
index 0000000..dad937f
--- /dev/null
+++ b/docs/diagrams/out/seq-hery-entity-list.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/diagrams/out/seq-hery-entity-validate-dark.svg b/docs/diagrams/out/seq-hery-entity-validate-dark.svg
new file mode 100644
index 0000000..891a8b1
--- /dev/null
+++ b/docs/diagrams/out/seq-hery-entity-validate-dark.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/diagrams/out/seq-hery-entity-validate.svg b/docs/diagrams/out/seq-hery-entity-validate.svg
new file mode 100644
index 0000000..c0f6777
--- /dev/null
+++ b/docs/diagrams/out/seq-hery-entity-validate.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/diagrams/out/seq-hery-entity.svg b/docs/diagrams/out/seq-hery-entity.svg
new file mode 100644
index 0000000..be970a8
--- /dev/null
+++ b/docs/diagrams/out/seq-hery-entity.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/diagrams/out/seq-hery-query-dark.svg b/docs/diagrams/out/seq-hery-query-dark.svg
new file mode 100644
index 0000000..93a4276
--- /dev/null
+++ b/docs/diagrams/out/seq-hery-query-dark.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/diagrams/out/seq-hery-query.svg b/docs/diagrams/out/seq-hery-query.svg
new file mode 100644
index 0000000..4aebdce
--- /dev/null
+++ b/docs/diagrams/out/seq-hery-query.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/diagrams/out/seq-hery-settings-dark.svg b/docs/diagrams/out/seq-hery-settings-dark.svg
new file mode 100644
index 0000000..29e58a8
--- /dev/null
+++ b/docs/diagrams/out/seq-hery-settings-dark.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/diagrams/out/seq-hery-settings.svg b/docs/diagrams/out/seq-hery-settings.svg
new file mode 100644
index 0000000..ae3637d
--- /dev/null
+++ b/docs/diagrams/out/seq-hery-settings.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/diagrams/src/seq-hery-compose.puml b/docs/diagrams/src/seq-hery-compose.puml
new file mode 100644
index 0000000..8ab1440
--- /dev/null
+++ b/docs/diagrams/src/seq-hery-compose.puml
@@ -0,0 +1,47 @@
+@startuml seq-hery-compose
+
+title hery compose — Flatten Entities
+
+skinparam sequenceArrowThickness 1.5
+skinparam sequenceParticipantBorderColor #444
+
+actor "User" as user
+participant "cmd/" as cmd
+participant "entity/resolve/" as resolve
+participant "entity/compose/" as compose
+participant "storage/" as storage
+participant "entity/" as ent
+participant "entity/merge/" as merge
+participant "Filesystem" as fs
+
+== Local directory: --dir ==
+
+user -> cmd : hery compose --dir [--layer N]
+cmd -> resolve : Resolve(dir)
+resolve -> fs : Read *.hery per directory\n(breadth-first over layers)
+resolve -> resolve : Order documents by _requires
+resolve -> merge : OrderedDeepMerge for\nlocal ./ _extends refs
+resolve --> cmd : Merge layers + warnings\n(non-local refs warn, stay unmerged)
+cmd --> user : Warnings on stderr
+cmd --> user : Multi-document YAML on stdout\n(--layer N emits one layer)
+
+== Cached entity: positional URI ==
+
+user -> cmd : hery compose
+cmd -> compose : ComposeEntity(uri)
+compose -> storage : Paths()
+compose -> ent : ReadAll(entity cache)
+ent -> fs : Read every cached *.hery
+compose -> merge : ResolveExtendsChain\n+ DeepMerge per document
+merge --> compose : Resolved documents
+compose -> merge : DeepMerge all into one
+compose --> cmd : Single merged document
+cmd --> user : YAML on stdout\n(or ./composed.hery when --print=false)
+
+== Errors ==
+
+user -> cmd : hery compose (no arg, no --dir)
+cmd --> user : "entity argument required" + usage, exit 1
+cmd --> user : --layer N beyond resolved layers:\nerror on stderr, exit 1
+
+@enduml
diff --git a/docs/diagrams/src/seq-hery-entity-get.puml b/docs/diagrams/src/seq-hery-entity-get.puml
new file mode 100644
index 0000000..4f197a1
--- /dev/null
+++ b/docs/diagrams/src/seq-hery-entity-get.puml
@@ -0,0 +1,54 @@
+@startuml seq-hery-entity-get
+
+title hery entity get — Fetch Entities into the Cache
+
+skinparam sequenceArrowThickness 1.5
+skinparam sequenceParticipantBorderColor #444
+
+actor "User" as user
+participant "cmd/" as cmd
+participant "entity/cmd/" as ecmd
+participant "storage/" as storage
+participant "entity/get/" as get
+participant "entity/build/" as build
+participant "entity/version/" as version
+participant "Git remote" as git
+participant "entity/" as ent
+participant "entity/merge/" as merge
+participant "Filesystem\n(~/.cache/hery/entity)" as fs
+
+== Resolving versions ==
+
+user -> cmd : hery entity get ...
+cmd -> ecmd : GetCmd.Run
+ecmd -> storage : Paths()\n(HERY_STORAGE_PATH or ~/.cache/hery)
+ecmd -> get : Get(paths, uris)
+get -> build : Meta(uri) for each URI
+build -> version : Resolve version
+version -> git : List remote tags
+git --> version : Tags
+version --> build : Latest tag, explicit @version,\nor pseudo-version from HEAD hash
+
+== Downloading ==
+
+get -> fs : MkdirAll /
+get -> git : Clone repository\n(one goroutine per entity)
+git --> fs : Working tree
+get -> git : Checkout tag\n(skipped for pseudo-versions)
+get -> ent : ReadAll(entity dir)
+ent -> fs : Read every *.hery file
+
+== Resolving references ==
+
+get -> merge : ResolveExtendsChain per document
+merge -> build : Meta for _extends / _type URIs
+build -> git : Fetch referenced entities\n(recursive clone)
+merge -> merge : DeepMerge parent into child
+get --> ecmd : Done — silent on success\n(no SQLite writes)
+
+== Fetch failure ==
+
+git --> get : Clone / unknown tag error
+get --> user : Error on stderr, exit 1
+
+@enduml
diff --git a/docs/diagrams/src/seq-hery-entity-init.puml b/docs/diagrams/src/seq-hery-entity-init.puml
new file mode 100644
index 0000000..dc59f8f
--- /dev/null
+++ b/docs/diagrams/src/seq-hery-entity-init.puml
@@ -0,0 +1,29 @@
+@startuml seq-hery-entity-init
+
+title hery entity init — Scaffold a New Entity
+
+skinparam sequenceArrowThickness 1.5
+skinparam sequenceParticipantBorderColor #444
+
+actor "User" as user
+participant "cmd/" as cmd
+participant "entity/cmd/" as ecmd
+participant "Filesystem\n(current dir)" as fs
+
+== Scaffolding ==
+
+user -> cmd : hery entity init
+cmd -> ecmd : InitCmd.Run
+ecmd -> ecmd : Derive from URI\n(basename, @version stripped)
+ecmd -> fs : Write ./.hery.json\n(JSON Schema draft 2020-12 stub,\n$id urn:hery:)
+ecmd --> user : Created ./.hery.json
+ecmd -> fs : Write ./default.hery\n(_type: , empty _body)
+ecmd --> user : Created ./default.hery
+
+== Write failure ==
+
+ecmd -> fs : Write file
+fs --> ecmd : Permission denied
+ecmd --> user : Error on stderr, exit 1
+
+@enduml
diff --git a/docs/diagrams/src/seq-hery-entity-list.puml b/docs/diagrams/src/seq-hery-entity-list.puml
new file mode 100644
index 0000000..eeea132
--- /dev/null
+++ b/docs/diagrams/src/seq-hery-entity-list.puml
@@ -0,0 +1,35 @@
+@startuml seq-hery-entity-list
+
+title hery entity list — List Cached Entities
+
+skinparam sequenceArrowThickness 1.5
+skinparam sequenceParticipantBorderColor #444
+
+actor "User" as user
+participant "cmd/" as cmd
+participant "entity/cmd/" as ecmd
+participant "storage/" as storage
+participant "entity/" as ent
+participant "Filesystem\n(~/.cache/hery/entity)" as fs
+
+== Scanning the entity cache ==
+
+user -> cmd : hery entity list
+cmd -> ecmd : ListCmd.Run
+ecmd -> storage : Paths()
+storage --> ecmd : Entities dir
+ecmd -> ent : CrawlDirectoriesParallel(dir)
+ent -> fs : Walk + stat directories\n(10 parallel workers)
+fs --> ent : Dirs matching @
+ent --> ecmd : map of name to\n{origin, version}
+
+== Output ==
+
+ecmd --> user : Entity Origin | Entity Name | Version\ntable on stdout
+
+== Cache dir missing ==
+
+ent --> ecmd : Walk error
+ecmd --> user : Error message printed,\nexit 0
+
+@enduml
diff --git a/docs/diagrams/src/seq-hery-entity-validate.puml b/docs/diagrams/src/seq-hery-entity-validate.puml
new file mode 100644
index 0000000..9959e37
--- /dev/null
+++ b/docs/diagrams/src/seq-hery-entity-validate.puml
@@ -0,0 +1,48 @@
+@startuml seq-hery-entity-validate
+
+title hery entity valid — Validate Cached Entities
+
+skinparam sequenceArrowThickness 1.5
+skinparam sequenceParticipantBorderColor #444
+
+actor "User" as user
+participant "cmd/" as cmd
+participant "entity/cmd/" as ecmd
+participant "storage/" as storage
+participant "entity/" as ent
+participant "entity/validation/" as val
+participant "entity/get/" as get
+participant "Filesystem" as fs
+
+== Validate everything: --all ==
+
+user -> cmd : hery entity valid --all
+cmd -> ecmd : ValidateCmd.Run
+ecmd -> storage : Paths()
+ecmd -> ent : CrawlDirectoriesParallel(entities dir)
+ent -> fs : Walk entity cache
+ent --> ecmd : Cached entities
+loop each entity
+ ecmd -> ent : ReadAll(entity path)
+ ent -> fs : Read *.hery documents
+ ecmd -> val : Entity(document)
+ val --> ecmd : valid / validation failed
+ ecmd --> user : Per-document result on stdout
+end
+
+== Fetch and inspect: --rm ==
+
+user -> cmd : hery entity valid --rm
+cmd -> ecmd : ValidateCmd.Run
+ecmd -> get : GetInTmp(uris)
+get -> storage : TmpPaths()\n(mktemp hery_*)
+get -> get : Full get flow:\nresolve, clone, read, merge
+get --> ecmd : Temp entities dir
+ecmd --> user : Temp path printed
+
+== No arguments ==
+
+user -> cmd : hery entity valid
+cmd --> user : Help text, exit 0
+
+@enduml
diff --git a/docs/diagrams/src/seq-hery-entity.puml b/docs/diagrams/src/seq-hery-entity.puml
new file mode 100644
index 0000000..61f1687
--- /dev/null
+++ b/docs/diagrams/src/seq-hery-entity.puml
@@ -0,0 +1,32 @@
+@startuml seq-hery-entity
+
+title hery entity — Subcommand Dispatch
+
+skinparam sequenceArrowThickness 1.5
+skinparam sequenceParticipantBorderColor #444
+
+actor "User" as user
+participant "cmd/" as cmd
+participant "entity/cmd/" as ecmd
+
+== Registration (process start) ==
+
+cmd -> ecmd : Register subcommands:\ninit, get, list, valid\n(package init, before Execute)
+
+== Dispatch ==
+
+user -> cmd : hery entity
+cmd -> ecmd : Route to the subcommand's Run
+ecmd --> user : Subcommand output
+
+== Bare invocation ==
+
+user -> cmd : hery entity
+cmd --> user : Help text on stdout,\nexit 0
+
+== Unknown subcommand ==
+
+user -> cmd : hery entity bogus
+cmd --> user : unknown command error\n+ usage on stderr, exit 1
+
+@enduml
diff --git a/docs/diagrams/src/seq-hery-query.puml b/docs/diagrams/src/seq-hery-query.puml
new file mode 100644
index 0000000..a7d26d4
--- /dev/null
+++ b/docs/diagrams/src/seq-hery-query.puml
@@ -0,0 +1,50 @@
+@startuml seq-hery-query
+
+title hery query — Two-Stage Entity Query
+
+skinparam sequenceArrowThickness 1.5
+skinparam sequenceParticipantBorderColor #444
+
+actor "User" as user
+participant "cmd/" as cmd
+participant "entity/query/" as query
+participant "cache/database/" as cdb
+database "SQLite\n(~/.cache/hery/hery.db)" as db
+participant "entity/resolve/" as resolve
+participant "Filesystem" as fs
+
+== Stage 1 — selection ==
+
+user -> cmd : hery query --type --meta --tag\n[--from | --dir] [--jq] [-o] [--hery]
+
+alt default source: cache
+ cmd -> cdb : Open hery.db (WAL mode)
+ cmd -> query : Query(selection opts)
+ query -> cdb : SELECT merged_json FROM entities\nWHERE type GLOB / meta LIKE ...
+ cdb -> db : Read rows
+ db --> query : merged_json rows,\ndecoded into documents
+else --from or -
+ cmd -> fs : Open file (or stdin)
+ cmd -> query : LoadDocs — sniff JSON vs\nmulti-doc YAML
+ cmd -> query : QueryDocs(selection opts)
+else --dir
+ cmd -> resolve : Resolve(dir) into merge layers
+ resolve -> fs : Read *.hery files
+ cmd --> user : Resolve warnings on stderr
+ cmd -> query : LoadDocs + QueryDocs\nover the layered docs
+end
+
+== Stage 2 — transformation ==
+
+cmd -> query : ApplyJQToAll(--jq expression)
+query --> cmd : Object results only
+
+== Output ==
+
+cmd --> user : table | json | yaml on stdout\n(--hery wraps in HERY envelope)\nexit 0, or exit 2 when no results
+
+== Errors ==
+
+cmd --> user : "hery query: " on stderr, exit 1\n(missing cache db, bad --jq,\n--from with --dir)
+
+@enduml
diff --git a/docs/diagrams/src/seq-hery-settings.puml b/docs/diagrams/src/seq-hery-settings.puml
new file mode 100644
index 0000000..b844ac8
--- /dev/null
+++ b/docs/diagrams/src/seq-hery-settings.puml
@@ -0,0 +1,39 @@
+@startuml seq-hery-settings
+
+title hery settings — Paths and Environment
+
+skinparam sequenceArrowThickness 1.5
+skinparam sequenceParticipantBorderColor #444
+
+actor "User" as user
+participant "cmd/" as cmd
+participant "storage/" as storage
+participant "env/" as env
+participant "Filesystem" as fs
+
+== Resolving the storage root ==
+
+user -> cmd : hery settings
+cmd -> storage : Main()
+storage -> storage : HERY_STORAGE_PATH if set,\nelse user cache dir + /hery
+storage --> cmd : Collections path
+
+== Collecting env vars ==
+
+cmd -> env : List()
+env -> fs : Parse env/types.go in the\ncurrent working directory
+fs --> env : Env var names
+env --> cmd : Names
+cmd -> cmd : os.Getenv for each name
+
+== Output ==
+
+cmd --> user : Setting | Value table\non stdout
+
+== Outside the source tree ==
+
+cmd -> env : List()
+env --> cmd : env/types.go not found
+cmd --> user : Error on stderr, exit 1
+
+@enduml
diff --git a/docs/superpowers/plans/2026-07-26-hery-command-diagrams.md b/docs/superpowers/plans/2026-07-26-hery-command-diagrams.md
new file mode 100644
index 0000000..0a6c1e8
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-26-hery-command-diagrams.md
@@ -0,0 +1,736 @@
+# hery Command Sequence Diagrams Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add 8 PlantUML sequence diagrams (one per hery subcommand) and a new "hery Commands" docs page to AmadlaOrg.github.io.
+
+**Architecture:** Plain PlantUML sequence sources in `docs/diagrams/src/seq-hery-*.puml`, rendered to light+dark SVG pairs by the existing `docs/diagrams/render.sh` (`make diagrams`). A new MkDocs page `docs/tools/hery-commands.md` embeds each pair with prose. Participants use the C3 component names from `c3-hery-internals.puml` so C4 zooms into C3.
+
+**Tech Stack:** PlantUML (jar at `~/.local/plantuml/plantuml.jar`), MkDocs Material, GNU Make.
+
+## Global Constraints
+
+- Repo: `/home/jn/Projects/Amadla/org/AmadlaOrg.github.io`, branch `docs/hery-command-diagrams` (already exists, spec committed on it). All commands below run from the repo root unless stated.
+- Git: human-only authorship, NO AI attribution trailers of any kind, commits scoped to this task only. Never commit `CLAUDE.md`, `.idea/`, `bin/`.
+- Diagram style (matches `docs/diagrams/src/seq-secret-resolution.puml`): `@startuml seq-hery-` header (output SVG is named after it), a `title` line, `skinparam sequenceArrowThickness 1.5`, `skinparam sequenceParticipantBorderColor #444`, `== phase ==` separators. No C4-PlantUML macros, no smetana pragma, no `cloud` elements.
+- Diagrams reflect the actual hery source (verified 2026-07-26), including where it contradicts intuition: `hery entity get` does NOT write to SQLite; no CLI command populates the cache table (`hery query` only reads it); `hery settings` parses `env/types.go` from the current working directory.
+- Every diagram must render without errors: `java -jar $HOME/.local/plantuml/plantuml.jar -checkonly docs/diagrams/src/.puml` exits 0.
+- Page images use Material light/dark pairs: `` + ``.
+
+---
+
+### Task 1: Dispatch + settings diagrams (the two simple ones)
+
+**Files:**
+- Create: `docs/diagrams/src/seq-hery-entity.puml`
+- Create: `docs/diagrams/src/seq-hery-settings.puml`
+
+**Interfaces:**
+- Produces: SVG basenames `seq-hery-entity` and `seq-hery-settings` referenced by Task 7's page.
+
+- [ ] **Step 1: Write `docs/diagrams/src/seq-hery-entity.puml`**
+
+```plantuml
+@startuml seq-hery-entity
+
+title hery entity — Subcommand Dispatch
+
+skinparam sequenceArrowThickness 1.5
+skinparam sequenceParticipantBorderColor #444
+
+actor "User" as user
+participant "cmd/" as cmd
+participant "entity/cmd/" as ecmd
+
+== Registration (process start) ==
+
+cmd -> ecmd : Register subcommands:\ninit, get, list, valid\n(package init, before Execute)
+
+== Dispatch ==
+
+user -> cmd : hery entity
+cmd -> ecmd : Route to the subcommand's Run
+ecmd --> user : Subcommand output
+
+== Bare invocation ==
+
+user -> cmd : hery entity
+cmd --> user : Help text on stdout,\nexit 0
+
+== Unknown subcommand ==
+
+user -> cmd : hery entity bogus
+cmd --> user : unknown command error\n+ usage on stderr, exit 1
+
+@enduml
+```
+
+- [ ] **Step 2: Write `docs/diagrams/src/seq-hery-settings.puml`**
+
+```plantuml
+@startuml seq-hery-settings
+
+title hery settings — Paths and Environment
+
+skinparam sequenceArrowThickness 1.5
+skinparam sequenceParticipantBorderColor #444
+
+actor "User" as user
+participant "cmd/" as cmd
+participant "storage/" as storage
+participant "env/" as env
+participant "Filesystem" as fs
+
+== Resolving the storage root ==
+
+user -> cmd : hery settings
+cmd -> storage : Main()
+storage -> storage : HERY_STORAGE_PATH if set,\nelse user cache dir + /hery
+storage --> cmd : Collections path
+
+== Collecting env vars ==
+
+cmd -> env : List()
+env -> fs : Parse env/types.go in the\ncurrent working directory
+fs --> env : Env var names
+env --> cmd : Names
+cmd -> cmd : os.Getenv for each name
+
+== Output ==
+
+cmd --> user : Setting | Value table\non stdout
+
+== Outside the source tree ==
+
+cmd -> env : List()
+env --> cmd : env/types.go not found
+cmd --> user : Error on stderr, exit 1
+
+@enduml
+```
+
+- [ ] **Step 3: Verify both render**
+
+Run: `java -jar $HOME/.local/plantuml/plantuml.jar -checkonly docs/diagrams/src/seq-hery-entity.puml docs/diagrams/src/seq-hery-settings.puml && echo OK`
+Expected: `OK` (exit 0, no syntax errors)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add docs/diagrams/src/seq-hery-entity.puml docs/diagrams/src/seq-hery-settings.puml
+git commit -m "Add sequence diagrams for hery entity dispatch and hery settings"
+```
+
+---
+
+### Task 2: entity init + entity list diagrams
+
+**Files:**
+- Create: `docs/diagrams/src/seq-hery-entity-init.puml`
+- Create: `docs/diagrams/src/seq-hery-entity-list.puml`
+
+**Interfaces:**
+- Produces: SVG basenames `seq-hery-entity-init` and `seq-hery-entity-list` referenced by Task 7's page.
+
+- [ ] **Step 1: Write `docs/diagrams/src/seq-hery-entity-init.puml`**
+
+```plantuml
+@startuml seq-hery-entity-init
+
+title hery entity init — Scaffold a New Entity
+
+skinparam sequenceArrowThickness 1.5
+skinparam sequenceParticipantBorderColor #444
+
+actor "User" as user
+participant "cmd/" as cmd
+participant "entity/cmd/" as ecmd
+participant "Filesystem\n(current dir)" as fs
+
+== Scaffolding ==
+
+user -> cmd : hery entity init
+cmd -> ecmd : InitCmd.Run
+ecmd -> ecmd : Derive from URI\n(basename, @version stripped)
+ecmd -> fs : Write ./.hery.json\n(JSON Schema draft 2020-12 stub,\n$id urn:hery:)
+ecmd --> user : Created ./.hery.json
+ecmd -> fs : Write ./default.hery\n(_type: , empty _body)
+ecmd --> user : Created ./default.hery
+
+== Write failure ==
+
+ecmd -> fs : Write file
+fs --> ecmd : Permission denied
+ecmd --> user : Error on stderr, exit 1
+
+@enduml
+```
+
+- [ ] **Step 2: Write `docs/diagrams/src/seq-hery-entity-list.puml`**
+
+```plantuml
+@startuml seq-hery-entity-list
+
+title hery entity list — List Cached Entities
+
+skinparam sequenceArrowThickness 1.5
+skinparam sequenceParticipantBorderColor #444
+
+actor "User" as user
+participant "cmd/" as cmd
+participant "entity/cmd/" as ecmd
+participant "storage/" as storage
+participant "entity/" as ent
+participant "Filesystem\n(~/.cache/hery/entity)" as fs
+
+== Scanning the entity cache ==
+
+user -> cmd : hery entity list
+cmd -> ecmd : ListCmd.Run
+ecmd -> storage : Paths()
+storage --> ecmd : Entities dir
+ecmd -> ent : CrawlDirectoriesParallel(dir)
+ent -> fs : Walk + stat directories\n(10 parallel workers)
+fs --> ent : Dirs matching @
+ent --> ecmd : map of name to\n{origin, version}
+
+== Output ==
+
+ecmd --> user : Entity Origin | Entity Name | Version\ntable on stdout
+
+== Cache dir missing ==
+
+ent --> ecmd : Walk error
+ecmd --> user : Error message printed,\nexit 0
+
+@enduml
+```
+
+- [ ] **Step 3: Verify both render**
+
+Run: `java -jar $HOME/.local/plantuml/plantuml.jar -checkonly docs/diagrams/src/seq-hery-entity-init.puml docs/diagrams/src/seq-hery-entity-list.puml && echo OK`
+Expected: `OK`
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add docs/diagrams/src/seq-hery-entity-init.puml docs/diagrams/src/seq-hery-entity-list.puml
+git commit -m "Add sequence diagrams for hery entity init and list"
+```
+
+---
+
+### Task 3: entity get diagram (the complex one)
+
+**Files:**
+- Create: `docs/diagrams/src/seq-hery-entity-get.puml`
+
+**Interfaces:**
+- Produces: SVG basename `seq-hery-entity-get` referenced by Task 7's page.
+
+- [ ] **Step 1: Write `docs/diagrams/src/seq-hery-entity-get.puml`**
+
+```plantuml
+@startuml seq-hery-entity-get
+
+title hery entity get — Fetch Entities into the Cache
+
+skinparam sequenceArrowThickness 1.5
+skinparam sequenceParticipantBorderColor #444
+
+actor "User" as user
+participant "cmd/" as cmd
+participant "entity/cmd/" as ecmd
+participant "storage/" as storage
+participant "entity/get/" as get
+participant "entity/build/" as build
+participant "entity/version/" as version
+participant "Git remote" as git
+participant "entity/" as ent
+participant "entity/merge/" as merge
+participant "Filesystem\n(~/.cache/hery/entity)" as fs
+
+== Resolving versions ==
+
+user -> cmd : hery entity get ...
+cmd -> ecmd : GetCmd.Run
+ecmd -> storage : Paths()\n(HERY_STORAGE_PATH or ~/.cache/hery)
+ecmd -> get : Get(paths, uris)
+get -> build : Meta(uri) for each URI
+build -> version : Resolve version
+version -> git : List remote tags
+git --> version : Tags
+version --> build : Latest tag, explicit @version,\nor pseudo-version from HEAD hash
+
+== Downloading ==
+
+get -> fs : MkdirAll /
+get -> git : Clone repository\n(one goroutine per entity)
+git --> fs : Working tree
+get -> git : Checkout tag\n(skipped for pseudo-versions)
+get -> ent : ReadAll(entity dir)
+ent -> fs : Read every *.hery file
+
+== Resolving references ==
+
+get -> merge : ResolveExtendsChain per document
+merge -> build : Meta for _extends / _type URIs
+build -> git : Fetch referenced entities\n(recursive clone)
+merge -> merge : DeepMerge parent into child
+get --> ecmd : Done — silent on success\n(no SQLite writes)
+
+== Fetch failure ==
+
+git --> get : Clone / unknown tag error
+get --> user : Error on stderr, exit 1
+
+@enduml
+```
+
+- [ ] **Step 2: Verify it renders**
+
+Run: `java -jar $HOME/.local/plantuml/plantuml.jar -checkonly docs/diagrams/src/seq-hery-entity-get.puml && echo OK`
+Expected: `OK`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add docs/diagrams/src/seq-hery-entity-get.puml
+git commit -m "Add sequence diagram for hery entity get"
+```
+
+---
+
+### Task 4: entity valid diagram
+
+**Files:**
+- Create: `docs/diagrams/src/seq-hery-entity-validate.puml`
+
+**Interfaces:**
+- Produces: SVG basename `seq-hery-entity-validate` referenced by Task 7's page.
+
+- [ ] **Step 1: Write `docs/diagrams/src/seq-hery-entity-validate.puml`**
+
+Note: the CLI verb is `valid` (`hery entity valid`); the file keeps the spec's `validate` basename.
+
+```plantuml
+@startuml seq-hery-entity-validate
+
+title hery entity valid — Validate Cached Entities
+
+skinparam sequenceArrowThickness 1.5
+skinparam sequenceParticipantBorderColor #444
+
+actor "User" as user
+participant "cmd/" as cmd
+participant "entity/cmd/" as ecmd
+participant "storage/" as storage
+participant "entity/" as ent
+participant "entity/validation/" as val
+participant "entity/get/" as get
+participant "Filesystem" as fs
+
+== Validate everything: --all ==
+
+user -> cmd : hery entity valid --all
+cmd -> ecmd : ValidateCmd.Run
+ecmd -> storage : Paths()
+ecmd -> ent : CrawlDirectoriesParallel(entities dir)
+ent -> fs : Walk entity cache
+ent --> ecmd : Cached entities
+loop each entity
+ ecmd -> ent : ReadAll(entity path)
+ ent -> fs : Read *.hery documents
+ ecmd -> val : Entity(document)
+ val --> ecmd : valid / validation failed
+ ecmd --> user : Per-document result on stdout
+end
+
+== Fetch and inspect: --rm ==
+
+user -> cmd : hery entity valid --rm
+cmd -> ecmd : ValidateCmd.Run
+ecmd -> get : GetInTmp(uris)
+get -> storage : TmpPaths()\n(mktemp hery_*)
+get -> get : Full get flow:\nresolve, clone, read, merge
+get --> ecmd : Temp entities dir
+ecmd --> user : Temp path printed
+
+== No arguments ==
+
+user -> cmd : hery entity valid
+cmd --> user : Help text, exit 0
+
+@enduml
+```
+
+- [ ] **Step 2: Verify it renders**
+
+Run: `java -jar $HOME/.local/plantuml/plantuml.jar -checkonly docs/diagrams/src/seq-hery-entity-validate.puml && echo OK`
+Expected: `OK`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add docs/diagrams/src/seq-hery-entity-validate.puml
+git commit -m "Add sequence diagram for hery entity valid"
+```
+
+---
+
+### Task 5: query diagram
+
+**Files:**
+- Create: `docs/diagrams/src/seq-hery-query.puml`
+
+**Interfaces:**
+- Produces: SVG basename `seq-hery-query` referenced by Task 7's page.
+
+- [ ] **Step 1: Write `docs/diagrams/src/seq-hery-query.puml`**
+
+```plantuml
+@startuml seq-hery-query
+
+title hery query — Two-Stage Entity Query
+
+skinparam sequenceArrowThickness 1.5
+skinparam sequenceParticipantBorderColor #444
+
+actor "User" as user
+participant "cmd/" as cmd
+participant "entity/query/" as query
+participant "cache/database/" as cdb
+database "SQLite\n(~/.cache/hery/hery.db)" as db
+participant "entity/resolve/" as resolve
+participant "Filesystem" as fs
+
+== Stage 1 — selection ==
+
+user -> cmd : hery query --type --meta --tag\n[--from | --dir] [--jq] [-o] [--hery]
+
+alt default source: cache
+ cmd -> cdb : Open hery.db (WAL mode)
+ cmd -> query : Query(selection opts)
+ query -> cdb : SELECT merged_json FROM entities\nWHERE type GLOB / meta LIKE ...
+ cdb -> db : Read rows
+ db --> query : merged_json rows,\ndecoded into documents
+else --from or -
+ cmd -> fs : Open file (or stdin)
+ cmd -> query : LoadDocs — sniff JSON vs\nmulti-doc YAML
+ cmd -> query : QueryDocs(selection opts)
+else --dir
+ cmd -> resolve : Resolve(dir) into merge layers
+ resolve -> fs : Read *.hery files
+ cmd --> user : Resolve warnings on stderr
+ cmd -> query : LoadDocs + QueryDocs\nover the layered docs
+end
+
+== Stage 2 — transformation ==
+
+cmd -> query : ApplyJQToAll(--jq expression)
+query --> cmd : Object results only
+
+== Output ==
+
+cmd --> user : table | json | yaml on stdout\n(--hery wraps in HERY envelope)\nexit 0, or exit 2 when no results
+
+== Errors ==
+
+cmd --> user : "hery query: " on stderr, exit 1\n(missing cache db, bad --jq,\n--from with --dir)
+
+@enduml
+```
+
+- [ ] **Step 2: Verify it renders**
+
+Run: `java -jar $HOME/.local/plantuml/plantuml.jar -checkonly docs/diagrams/src/seq-hery-query.puml && echo OK`
+Expected: `OK`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add docs/diagrams/src/seq-hery-query.puml
+git commit -m "Add sequence diagram for hery query"
+```
+
+---
+
+### Task 6: compose diagram
+
+**Files:**
+- Create: `docs/diagrams/src/seq-hery-compose.puml`
+
+**Interfaces:**
+- Produces: SVG basename `seq-hery-compose` referenced by Task 7's page.
+
+- [ ] **Step 1: Write `docs/diagrams/src/seq-hery-compose.puml`**
+
+```plantuml
+@startuml seq-hery-compose
+
+title hery compose — Flatten Entities
+
+skinparam sequenceArrowThickness 1.5
+skinparam sequenceParticipantBorderColor #444
+
+actor "User" as user
+participant "cmd/" as cmd
+participant "entity/resolve/" as resolve
+participant "entity/compose/" as compose
+participant "storage/" as storage
+participant "entity/" as ent
+participant "entity/merge/" as merge
+participant "Filesystem" as fs
+
+== Local directory: --dir ==
+
+user -> cmd : hery compose --dir [--layer N]
+cmd -> resolve : Resolve(dir)
+resolve -> fs : Read *.hery per directory\n(breadth-first over layers)
+resolve -> resolve : Order documents by _requires
+resolve -> merge : OrderedDeepMerge for\nlocal ./ _extends refs
+resolve --> cmd : Merge layers + warnings\n(non-local refs warn, stay unmerged)
+cmd --> user : Warnings on stderr
+cmd --> user : Multi-document YAML on stdout\n(--layer N emits one layer)
+
+== Cached entity: positional URI ==
+
+user -> cmd : hery compose
+cmd -> compose : ComposeEntity(uri)
+compose -> storage : Paths()
+compose -> ent : ReadAll(entity cache)
+ent -> fs : Read every cached *.hery
+compose -> merge : ResolveExtendsChain\n+ DeepMerge per document
+merge --> compose : Resolved documents
+compose -> merge : DeepMerge all into one
+compose --> cmd : Single merged document
+cmd --> user : YAML on stdout\n(or ./composed.hery when --print=false)
+
+== Errors ==
+
+user -> cmd : hery compose (no arg, no --dir)
+cmd --> user : "entity argument required" + usage, exit 1
+cmd --> user : --layer N beyond resolved layers:\nerror on stderr, exit 1
+
+@enduml
+```
+
+- [ ] **Step 2: Verify it renders**
+
+Run: `java -jar $HOME/.local/plantuml/plantuml.jar -checkonly docs/diagrams/src/seq-hery-compose.puml && echo OK`
+Expected: `OK`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add docs/diagrams/src/seq-hery-compose.puml
+git commit -m "Add sequence diagram for hery compose"
+```
+
+---
+
+### Task 7: hery Commands page, nav, cross-link, exclude_docs
+
+**Files:**
+- Create: `docs/tools/hery-commands.md`
+- Modify: `mkdocs.yml` (nav entry after `hery: tools/hery.md`; add `superpowers/` to `exclude_docs`)
+- Modify: `docs/tools/hery.md` (one link line in the Commands section)
+
+**Interfaces:**
+- Consumes: the 8 SVG basenames from Tasks 1-6 (`seq-hery-entity`, `seq-hery-settings`, `seq-hery-entity-init`, `seq-hery-entity-list`, `seq-hery-entity-get`, `seq-hery-entity-validate`, `seq-hery-query`, `seq-hery-compose`). The SVGs themselves are produced in Task 8; strict build happens there.
+
+- [ ] **Step 1: Write `docs/tools/hery-commands.md`**
+
+```markdown
+# hery Commands
+
+Sequence diagrams for each `hery` subcommand — the C4 dynamics level of the
+[hery architecture](hery.md). Participants are the internal components from
+the [C3 diagram](hery.md#architecture), so each diagram zooms into the same
+boxes: `cmd/`, `entity/cmd/`, `entity/get/`, `entity/resolve/`,
+`entity/merge/`, `entity/compose/`, `entity/query/`, `entity/validation/`,
+`entity/version/`, `entity/build/`, `cache/database/`, `storage/` — plus
+the externals they talk to (filesystem, Git remotes, SQLite).
+
+## hery entity
+
+Namespace command that groups the entity lifecycle subcommands: `init`,
+`get`, `list`, and `valid`. Run bare it prints their help; an unknown
+subcommand exits non-zero with usage on stderr.
+
+
+
+
+## hery entity init
+
+Scaffolds a new entity in the current directory: a starter JSON Schema
+(`.hery.json`, draft 2020-12, `$id` derived from the URI) and a stub
+`default.hery` document carrying the `_type`. Existing files are
+overwritten, so run it in a fresh directory.
+
+
+
+
+## hery entity get
+
+Fetches entities into the global cache (`HERY_STORAGE_PATH` or
+`~/.cache/hery/entity`). Each URI is resolved to a concrete version from
+the repository's Git tags — latest tag, an explicit `@version`, or a
+generated pseudo-version when the repo has no tags — then the repo is
+cloned and every `.hery` document it contains is read. References made
+through `_extends` and `_type` are fetched recursively and deep-merged.
+Success is silent; note that `get` populates the on-disk entity cache only,
+not the SQLite database `hery query` reads.
+
+
+
+
+## hery entity list
+
+Scans the entity cache directory and prints a table of every downloaded
+entity's origin, name, and version. A missing or empty cache prints a
+message and exits zero — listing nothing is not an error.
+
+
+
+
+## hery entity valid
+
+Validates cached entity documents. `--all` walks the whole entity cache
+and reports each document as valid or failed; `--rm ` instead fetches
+the named entities into a throwaway temp directory and prints its path.
+Run bare it prints its help.
+
+
+
+
+## hery query
+
+The two-stage query model. Stage 1 selects entities — by default from the
+SQLite cache (`~/.cache/hery/hery.db`), or from a YAML/JSON file or stdin
+with `--from`, or from a resolved directory of `.hery` files with `--dir`
+— filtering on `--type` (glob), `--meta`, and `--tag`. Stage 2 optionally
+transforms each selected document with a `--jq` expression. Output is a
+table, JSON, or YAML (`-o`), optionally wrapped in a HERY envelope with
+`--hery`. Exit code 2 means the query ran but matched nothing, grep-style.
+
+
+
+
+## hery compose
+
+Flattens entities into their final form. With `--dir`, a local directory
+of `.hery` files is resolved into ordered merge layers — `_requires`
+ordering within a layer, local `_extends` deep-merged, non-local
+references left as warnings — and emitted as a multi-document YAML stream
+(`--layer N` picks one layer); this is the stream `raise up -f -`
+consumes. With a positional entity URI, the cached entity's `_extends`
+chain is deep-merged into a single document, printed by default or written
+to `./composed.hery` with `--print=false`.
+
+
+
+
+## hery settings
+
+Prints a table of hery's resolved storage root (`HERY_STORAGE_PATH` or the
+user cache dir) and the current values of hery's environment variables.
+
+
+
+```
+
+- [ ] **Step 2: Add the nav entry in `mkdocs.yml`**
+
+Find (around line 61):
+
+```yaml
+ - hery: tools/hery.md
+```
+
+Change to:
+
+```yaml
+ - hery: tools/hery.md
+ - hery Commands: tools/hery-commands.md
+```
+
+- [ ] **Step 3: Extend `exclude_docs` in `mkdocs.yml`**
+
+Find:
+
+```yaml
+exclude_docs: |
+ diagrams/vendor/
+```
+
+Change to:
+
+```yaml
+exclude_docs: |
+ diagrams/vendor/
+ superpowers/
+```
+
+- [ ] **Step 4: Link from `docs/tools/hery.md`**
+
+At the end of the `## Commands` section (before `## Dependencies`), add:
+
+```markdown
+Per-command sequence diagrams: [hery Commands](hery-commands.md).
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add docs/tools/hery-commands.md docs/tools/hery.md mkdocs.yml
+git commit -m "Add hery Commands page with per-command diagram sections"
+```
+
+---
+
+### Task 8: Render, build strict, visual check, PR
+
+**Files:**
+- Create (generated): `docs/diagrams/out/seq-hery-*.svg` and `docs/diagrams/out/seq-hery-*-dark.svg` (16 files)
+
+**Interfaces:**
+- Consumes: all 8 `.puml` sources and the Task 7 page.
+
+- [ ] **Step 1: Render all diagrams**
+
+Run: `make diagrams`
+Expected: ends with `==> done: N files in out/` and `ls docs/diagrams/out/seq-hery-*.svg | wc -l` prints 16.
+
+- [ ] **Step 2: Strict MkDocs build**
+
+Run: `mkdocs build --strict 2>&1 | tail -5`
+Expected: build completes with no warnings/errors (strict mode aborts on any). If it fails on a missing anchor `hery.md#architecture`, check the heading id on the built hery page and fix the link in `hery-commands.md`.
+
+- [ ] **Step 3: Visual check of one pair**
+
+Open `docs/diagrams/out/seq-hery-query.svg` and `seq-hery-query-dark.svg` (send them to the user or view in browser). Confirm: title renders, participants labeled, dark variant uses the dark palette.
+
+- [ ] **Step 4: Commit rendered SVGs**
+
+```bash
+git add docs/diagrams/out/seq-hery-*.svg
+git commit -m "Render hery command sequence diagrams (light + dark)"
+```
+
+- [ ] **Step 5: Push and open PR**
+
+```bash
+git push -u origin docs/hery-command-diagrams
+gh pr create --title "Add per-command sequence diagrams for hery" --body "..."
+```
+
+PR body must summarize the change and list the spec-vs-code corrections (no AI attribution): `entity get` writes only the on-disk cache, never SQLite; no CLI command populates the SQLite `entities` table (`query` reads it only); `settings` reads `env/types.go` from the cwd, so it fails outside the source tree; the validate verb is `valid`; `entity/schema/` is constructed but never invoked at runtime, so it appears in no diagram.
+
+---
+
+## Self-Review Notes
+
+- Spec coverage: 8 diagrams (Tasks 1-6), page + nav + link + exclude_docs (Task 7), render + strict build + visual check + PR (Task 8). All spec sections covered.
+- Code-truth corrections applied: no SQLite writes in `entity get` (spec sketch said otherwise — PR body notes it); `entity/schema/` omitted from participants (never called at runtime); `env/` added as a participant in the settings diagram (real package, not in C3 — noted in PR body); list's missing-cache lane exits 0, not non-zero.
+- Type consistency: SVG basenames in Task 7's page match the `@startuml` names in Tasks 1-6 exactly (`seq-hery-entity`, `seq-hery-entity-init`, `seq-hery-entity-get`, `seq-hery-entity-list`, `seq-hery-entity-validate`, `seq-hery-query`, `seq-hery-compose`, `seq-hery-settings`).
diff --git a/docs/superpowers/specs/2026-07-26-hery-command-diagrams-design.md b/docs/superpowers/specs/2026-07-26-hery-command-diagrams-design.md
new file mode 100644
index 0000000..3e7c782
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-26-hery-command-diagrams-design.md
@@ -0,0 +1,108 @@
+# hery Command Sequence Diagrams (C4 level) — Design
+
+Date: 2026-07-26
+Repo: AmadlaOrg.github.io
+Status: approved design, pending implementation
+
+## Goal
+
+Complete the C4 model for the hery tool on the docs site. C1 (ecosystem
+context), C2 (pipeline/plugins/libraries), and C3 (hery internals) exist.
+This adds the code-dynamics level: one PlantUML sequence diagram per hery
+subcommand, embedded on a new "hery Commands" page with prose explanations
+in the page body (not baked into the images). hery only for now; other
+tools follow the same pattern later if this works well.
+
+## Notation and conventions
+
+Plain PlantUML sequence diagrams — the same style as the existing
+`seq-secret-resolution.puml` and `seq-pipeline-flow.puml`:
+
+- `@startuml seq-hery-` header naming (output SVG name comes from it)
+- `title` line, `skinparam sequenceArrowThickness 1.5`,
+ `skinparam sequenceParticipantBorderColor #444`
+- `== phase ==` separators, 2–3 phases per diagram
+- One error lane where genuinely informative (mirrors the "plugin missing"
+ lane in seq-secret-resolution)
+- No C4-PlantUML macros and no smetana pragma (those are for the C1–C3
+ component diagrams only); no `cloud` elements
+- Light + dark pairs come from `docs/diagrams/render.sh` (`make diagrams`);
+ nothing extra to do per diagram
+
+Participants are the C3 components from `c3-hery-internals.puml`
+(`cmd/`, `entity/cmd/`, `entity/build/`, `entity/get/`, `entity/resolve/`,
+`entity/merge/`, `entity/compose/`, `entity/query/`, `entity/validation/`,
+`entity/schema/`, `entity/version/`, `cache/`, `storage/`) plus externals:
+the user/caller, Git remotes, SQLite file, filesystem. C4 therefore zooms
+into C3 with consistent names. Only the participants a command actually
+touches appear in its diagram.
+
+## Files
+
+New diagram sources in `docs/diagrams/src/` (8):
+
+| File | Command | Sketch |
+|------|---------|--------|
+| `seq-hery-entity.puml` | `hery entity` | Parent dispatch: flag parsing in `cmd/`, delegation to `entity/cmd/` subcommands; unknown subcommand → usage on stderr, exit non-zero |
+| `seq-hery-entity-init.puml` | `hery entity init` | Scaffold a new entity: storage writes, schema stub |
+| `seq-hery-entity-get.puml` | `hery entity get` | Fetch from Git remote via `entity/get/` + `entity/version/` (tag resolution), build via `entity/build/` → `resolve/` → `merge/`, cache into SQLite |
+| `seq-hery-entity-list.puml` | `hery entity list` | List known entities from `cache/`; cold-cache lane hits `storage/` |
+| `seq-hery-entity-validate.puml` | `hery entity validate` | `entity/validation/` + `entity/schema/` against JSON Schema; invalid-document error lane |
+| `seq-hery-query.puml` | `hery query` | Two-stage model: selection flags pick entities (`--from` file/dir/cache), then `--jq` projection; output to stdout |
+| `seq-hery-compose.puml` | `hery compose` | `--dir`/`--layer` layering: `resolve/` + `merge/` flatten `_extends`, multi-doc/single-doc output to stdout (the `raise up -f -` pipe input) |
+| `seq-hery-settings.puml` | `hery settings` | Paths and env lookup; no cache involvement |
+
+Rendered outputs land in `docs/diagrams/out/` as `.svg` +
+`-dark.svg` (16 files) via `make diagrams`.
+
+Each diagram's message flow is verified against the hery source
+(`hery/cmd/`, `hery/entity/...`) as it is written — the table above is a
+sketch, the code is the truth. Where the sketch and code disagree, follow
+the code and note the difference in the PR description.
+
+## Page
+
+New `docs/tools/hery-commands.md`, nav entry under Tools directly after
+`hery`:
+
+```
+- hery: tools/hery.md
+- hery Commands: tools/hery-commands.md
+```
+
+Structure: short intro paragraph (what this page is, link back to
+`tools/hery.md` for the C3 architecture), then one `##` section per
+command in the table order above. Each section:
+
+1. 2–4 sentences of prose: what the command does, when you use it, what it
+ reads/writes, notable flags (`--from`, `--dir`, `--layer`, `--hery`,
+ `-o`). Prose lives in the page, never in the image.
+2. The image pair:
+ `` +
+ `#only-dark` twin.
+
+`docs/tools/hery.md` Commands section gets one line linking to the new
+page.
+
+`mkdocs.yml` `exclude_docs` gains a `superpowers/` line so this spec
+directory never enters the site build.
+
+## Verification
+
+- `make diagrams` renders all sources with zero PlantUML errors
+- `mkdocs build` in strict mode passes
+- Visual check of at least one light/dark pair
+- Participant names cross-checked against `c3-hery-internals.puml`
+
+## Workflow
+
+Branch `docs/hery-command-diagrams`, PR to master (repo's established
+flow). Human-only authorship, no AI trailers. Commits scoped: spec,
+diagrams+page, nav/link tweaks can land as one or few commits but nothing
+unrelated.
+
+## Out of scope
+
+Other tools' command diagrams, changes to the C1–C3 diagrams, hery CLI
+changes, `version`/`completion`/`help` subcommands (trivial, no diagram
+value).
diff --git a/docs/tools/hery-commands.md b/docs/tools/hery-commands.md
new file mode 100644
index 0000000..e22666a
--- /dev/null
+++ b/docs/tools/hery-commands.md
@@ -0,0 +1,97 @@
+# hery Commands
+
+Sequence diagrams for each `hery` subcommand — the C4 dynamics level of the
+[hery architecture](hery.md). Participants are the internal components from
+the [C3 diagram](hery.md#architecture), so each diagram zooms into the same
+boxes: `cmd/`, `entity/cmd/`, `entity/get/`, `entity/resolve/`,
+`entity/merge/`, `entity/compose/`, `entity/query/`, `entity/validation/`,
+`entity/version/`, `entity/build/`, `cache/database/`, `storage/` — plus
+`entity/` and `env/` where the code calls them directly, and the externals
+they talk to (filesystem, Git remotes, SQLite).
+
+## hery entity
+
+Namespace command that groups the entity lifecycle subcommands: `init`,
+`get`, `list`, and `valid`. Run bare it prints their help; an unknown
+subcommand exits non-zero with usage on stderr.
+
+
+
+
+## hery entity init
+
+Scaffolds a new entity in the current directory: a starter JSON Schema
+(`.hery.json`, draft 2020-12, `$id` derived from the URI) and a stub
+`default.hery` document carrying the `_type`. Existing files are
+overwritten, so run it in a fresh directory.
+
+
+
+
+## hery entity get
+
+Fetches entities into the global cache (`HERY_STORAGE_PATH` or
+`~/.cache/hery/entity`). Each URI is resolved to a concrete version from
+the repository's Git tags — latest tag, an explicit `@version`, or a
+generated pseudo-version when the repo has no tags — then the repo is
+cloned and every `.hery` document it contains is read. References made
+through `_extends` and `_type` are fetched recursively and deep-merged.
+Success is silent; note that `get` populates the on-disk entity cache only,
+not the SQLite database `hery query` reads.
+
+
+
+
+## hery entity list
+
+Scans the entity cache directory and prints a table of every downloaded
+entity's origin, name, and version. A missing or empty cache prints a
+message and exits zero — listing nothing is not an error.
+
+
+
+
+## hery entity valid
+
+Validates cached entity documents. `--all` walks the whole entity cache
+and reports each document as valid or failed; `--rm ` instead fetches
+the named entities into a throwaway temp directory and prints its path.
+Run bare it prints its help.
+
+
+
+
+## hery query
+
+The two-stage query model. Stage 1 selects entities — by default from the
+SQLite cache (`~/.cache/hery/hery.db`), or from a YAML/JSON file or stdin
+with `--from`, or from a resolved directory of `.hery` files with `--dir`
+— filtering on `--type` (glob), `--meta`, and `--tag`. Stage 2 optionally
+transforms each selected document with a `--jq` expression. Output is a
+table, JSON, or YAML (`-o`), optionally wrapped in a HERY envelope with
+`--hery`. Exit code 2 means the query ran but matched nothing, grep-style.
+
+
+
+
+## hery compose
+
+Flattens entities into their final form. With `--dir`, a local directory
+of `.hery` files is resolved into ordered merge layers — `_requires`
+ordering within a layer, local `_extends` deep-merged, non-local
+references left as warnings — and emitted as a multi-document YAML stream
+(`--layer N` picks one layer); this is the stream `raise up -f -`
+consumes. With a positional entity URI, the cached entity's `_extends`
+chain is deep-merged into a single document, printed by default or written
+to `./composed.hery` with `--print=false`.
+
+
+
+
+## hery settings
+
+Prints a table of hery's resolved storage root (`HERY_STORAGE_PATH` or the
+user cache dir) and the current values of hery's environment variables.
+
+
+
diff --git a/docs/tools/hery.md b/docs/tools/hery.md
index bf86856..5869fcc 100644
--- a/docs/tools/hery.md
+++ b/docs/tools/hery.md
@@ -10,12 +10,15 @@
| Command | Description |
|---------|-------------|
| `hery entity get` | Retrieve a specific entity |
+| `hery entity init` | Scaffold a new entity (schema stub + default.hery) |
| `hery entity list` | List entities |
-| `hery entity validate` | Validate entity content against JSON Schema |
+| `hery entity valid` | Validate entity content against JSON Schema |
| `hery query` | Query entities with selection flags + jq transformation |
| `hery compose` | Compose multiple entities into a unified view |
| `hery settings` | Manage hery configuration |
+Per-command sequence diagrams: [hery Commands](hery-commands.md).
+
## Dependencies
| Library | Purpose |
diff --git a/mkdocs.yml b/mkdocs.yml
index b912e93..bcd2b1f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -59,6 +59,7 @@ nav:
- Tools:
- Overview: tools/overview.md
- hery: tools/hery.md
+ - hery Commands: tools/hery-commands.md
- doorman: tools/doorman.md
- weaver: tools/weaver.md
- judge: tools/judge.md
@@ -315,6 +316,7 @@ extra:
# not part of this repo, which aborts the build in strict mode.
exclude_docs: |
diagrams/vendor/
+ superpowers/
plugins:
- search