From 517a4ac68e91686ffd89d8fb7577d11a296e2fe1 Mon Sep 17 00:00:00 2001 From: jnbdz Date: Sun, 26 Jul 2026 18:24:16 -0400 Subject: [PATCH 01/11] Add design spec for hery command sequence diagrams --- ...2026-07-26-hery-command-diagrams-design.md | 108 ++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-26-hery-command-diagrams-design.md 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: + `![...](../diagrams/out/seq-hery-.svg#only-light)` + + `#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). From 9d9c76d883071baefa202e4bfa3cb0186a2fa94c Mon Sep 17 00:00:00 2001 From: jnbdz Date: Sun, 26 Jul 2026 18:46:17 -0400 Subject: [PATCH 02/11] Add implementation plan for hery command sequence diagrams --- .../plans/2026-07-26-hery-command-diagrams.md | 736 ++++++++++++++++++ 1 file changed, 736 insertions(+) create mode 100644 docs/superpowers/plans/2026-07-26-hery-command-diagrams.md 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: `![alt](../diagrams/out/.svg#only-light)` + `![alt](../diagrams/out/-dark.svg#only-dark)`. + +--- + +### 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 dispatch](../diagrams/out/seq-hery-entity.svg#only-light) +![hery entity dispatch](../diagrams/out/seq-hery-entity-dark.svg#only-dark) + +## 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 init](../diagrams/out/seq-hery-entity-init.svg#only-light) +![hery entity init](../diagrams/out/seq-hery-entity-init-dark.svg#only-dark) + +## 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 get](../diagrams/out/seq-hery-entity-get.svg#only-light) +![hery entity get](../diagrams/out/seq-hery-entity-get-dark.svg#only-dark) + +## 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 list](../diagrams/out/seq-hery-entity-list.svg#only-light) +![hery entity list](../diagrams/out/seq-hery-entity-list-dark.svg#only-dark) + +## 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 entity valid](../diagrams/out/seq-hery-entity-validate.svg#only-light) +![hery entity valid](../diagrams/out/seq-hery-entity-validate-dark.svg#only-dark) + +## 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 query](../diagrams/out/seq-hery-query.svg#only-light) +![hery query](../diagrams/out/seq-hery-query-dark.svg#only-dark) + +## 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 compose](../diagrams/out/seq-hery-compose.svg#only-light) +![hery compose](../diagrams/out/seq-hery-compose-dark.svg#only-dark) + +## 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. + +![hery settings](../diagrams/out/seq-hery-settings.svg#only-light) +![hery settings](../diagrams/out/seq-hery-settings-dark.svg#only-dark) +``` + +- [ ] **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`). From 62683666747b3edfe8303f3216dfca68d54916d3 Mon Sep 17 00:00:00 2001 From: jnbdz Date: Sun, 26 Jul 2026 18:50:42 -0400 Subject: [PATCH 03/11] Add sequence diagrams for hery entity dispatch and hery settings --- docs/diagrams/src/seq-hery-entity.puml | 32 +++++++++++++++++++ docs/diagrams/src/seq-hery-settings.puml | 39 ++++++++++++++++++++++++ 2 files changed, 71 insertions(+) create mode 100644 docs/diagrams/src/seq-hery-entity.puml create mode 100644 docs/diagrams/src/seq-hery-settings.puml 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-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 From d8170ee49412ce67af0a475e99d5dd5c070f06c8 Mon Sep 17 00:00:00 2001 From: jnbdz Date: Sun, 26 Jul 2026 18:52:56 -0400 Subject: [PATCH 04/11] Add sequence diagrams for hery entity init and list --- docs/diagrams/src/seq-hery-entity-init.puml | 29 +++++++++++++++++ docs/diagrams/src/seq-hery-entity-list.puml | 35 +++++++++++++++++++++ 2 files changed, 64 insertions(+) create mode 100644 docs/diagrams/src/seq-hery-entity-init.puml create mode 100644 docs/diagrams/src/seq-hery-entity-list.puml 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 From 0e4e0e940962c5f107d0df7443903791f9f076fb Mon Sep 17 00:00:00 2001 From: jnbdz Date: Sun, 26 Jul 2026 18:56:47 -0400 Subject: [PATCH 05/11] Add sequence diagram for hery entity get --- docs/diagrams/src/seq-hery-entity-get.puml | 54 ++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 docs/diagrams/src/seq-hery-entity-get.puml 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 From 0f66d255200f56c3aaf3e294d353fa56289c8228 Mon Sep 17 00:00:00 2001 From: jnbdz Date: Sun, 26 Jul 2026 19:00:02 -0400 Subject: [PATCH 06/11] Add sequence diagram for hery entity valid --- .../src/seq-hery-entity-validate.puml | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 docs/diagrams/src/seq-hery-entity-validate.puml 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 From ed35717d7cdb4201a30393e1914544d759c9d837 Mon Sep 17 00:00:00 2001 From: jnbdz Date: Sun, 26 Jul 2026 19:03:15 -0400 Subject: [PATCH 07/11] Add sequence diagram for hery query --- docs/diagrams/src/seq-hery-query.puml | 50 +++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 docs/diagrams/src/seq-hery-query.puml 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 From 3d32230afd01cac9e1bc979315b0dcf6a786b4cb Mon Sep 17 00:00:00 2001 From: jnbdz Date: Sun, 26 Jul 2026 19:05:10 -0400 Subject: [PATCH 08/11] Add sequence diagram for hery compose --- docs/diagrams/src/seq-hery-compose.puml | 47 +++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 docs/diagrams/src/seq-hery-compose.puml 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 From 9b20cc81ae6b029a0612c84c4a3f42c0ca4f57b2 Mon Sep 17 00:00:00 2001 From: jnbdz Date: Sun, 26 Jul 2026 19:10:52 -0400 Subject: [PATCH 09/11] Add hery Commands page with per-command diagram sections --- docs/tools/hery-commands.md | 96 +++++++++++++++++++++++++++++++++++++ docs/tools/hery.md | 2 + mkdocs.yml | 2 + 3 files changed, 100 insertions(+) create mode 100644 docs/tools/hery-commands.md diff --git a/docs/tools/hery-commands.md b/docs/tools/hery-commands.md new file mode 100644 index 0000000..a5967f8 --- /dev/null +++ b/docs/tools/hery-commands.md @@ -0,0 +1,96 @@ +# 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 dispatch](../diagrams/out/seq-hery-entity.svg#only-light) +![hery entity dispatch](../diagrams/out/seq-hery-entity-dark.svg#only-dark) + +## 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 init](../diagrams/out/seq-hery-entity-init.svg#only-light) +![hery entity init](../diagrams/out/seq-hery-entity-init-dark.svg#only-dark) + +## 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 get](../diagrams/out/seq-hery-entity-get.svg#only-light) +![hery entity get](../diagrams/out/seq-hery-entity-get-dark.svg#only-dark) + +## 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 list](../diagrams/out/seq-hery-entity-list.svg#only-light) +![hery entity list](../diagrams/out/seq-hery-entity-list-dark.svg#only-dark) + +## 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 entity valid](../diagrams/out/seq-hery-entity-validate.svg#only-light) +![hery entity valid](../diagrams/out/seq-hery-entity-validate-dark.svg#only-dark) + +## 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 query](../diagrams/out/seq-hery-query.svg#only-light) +![hery query](../diagrams/out/seq-hery-query-dark.svg#only-dark) + +## 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 compose](../diagrams/out/seq-hery-compose.svg#only-light) +![hery compose](../diagrams/out/seq-hery-compose-dark.svg#only-dark) + +## 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. + +![hery settings](../diagrams/out/seq-hery-settings.svg#only-light) +![hery settings](../diagrams/out/seq-hery-settings-dark.svg#only-dark) diff --git a/docs/tools/hery.md b/docs/tools/hery.md index bf86856..1fd684c 100644 --- a/docs/tools/hery.md +++ b/docs/tools/hery.md @@ -16,6 +16,8 @@ | `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 From 3f3328fe688daf4e715f114c9750357870d33395 Mon Sep 17 00:00:00 2001 From: jnbdz Date: Sun, 26 Jul 2026 19:24:02 -0400 Subject: [PATCH 10/11] Render hery command sequence diagrams (light + dark) --- docs/diagrams/out/seq-hery-compose-dark.svg | 1 + docs/diagrams/out/seq-hery-compose.svg | 1 + docs/diagrams/out/seq-hery-entity-dark.svg | 1 + docs/diagrams/out/seq-hery-entity-get-dark.svg | 1 + docs/diagrams/out/seq-hery-entity-get.svg | 1 + docs/diagrams/out/seq-hery-entity-init-dark.svg | 1 + docs/diagrams/out/seq-hery-entity-init.svg | 1 + docs/diagrams/out/seq-hery-entity-list-dark.svg | 1 + docs/diagrams/out/seq-hery-entity-list.svg | 1 + docs/diagrams/out/seq-hery-entity-validate-dark.svg | 1 + docs/diagrams/out/seq-hery-entity-validate.svg | 1 + docs/diagrams/out/seq-hery-entity.svg | 1 + docs/diagrams/out/seq-hery-query-dark.svg | 1 + docs/diagrams/out/seq-hery-query.svg | 1 + docs/diagrams/out/seq-hery-settings-dark.svg | 1 + docs/diagrams/out/seq-hery-settings.svg | 1 + 16 files changed, 16 insertions(+) create mode 100644 docs/diagrams/out/seq-hery-compose-dark.svg create mode 100644 docs/diagrams/out/seq-hery-compose.svg create mode 100644 docs/diagrams/out/seq-hery-entity-dark.svg create mode 100644 docs/diagrams/out/seq-hery-entity-get-dark.svg create mode 100644 docs/diagrams/out/seq-hery-entity-get.svg create mode 100644 docs/diagrams/out/seq-hery-entity-init-dark.svg create mode 100644 docs/diagrams/out/seq-hery-entity-init.svg create mode 100644 docs/diagrams/out/seq-hery-entity-list-dark.svg create mode 100644 docs/diagrams/out/seq-hery-entity-list.svg create mode 100644 docs/diagrams/out/seq-hery-entity-validate-dark.svg create mode 100644 docs/diagrams/out/seq-hery-entity-validate.svg create mode 100644 docs/diagrams/out/seq-hery-entity.svg create mode 100644 docs/diagrams/out/seq-hery-query-dark.svg create mode 100644 docs/diagrams/out/seq-hery-query.svg create mode 100644 docs/diagrams/out/seq-hery-settings-dark.svg create mode 100644 docs/diagrams/out/seq-hery-settings.svg 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 @@ +hery compose — Flatten EntitiesUsercmd.entity.resolve.entity.compose.storage.entity.entity.merge.FilesystemUsercmd/entity/resolve/entity/compose/storage/entity/entity/merge/FilesystemLocal directory: --dirhery composedir <dir> [layer N]Resolve(dir)Read *.hery per directory(breadth-first over layers)Order documents by _requiresOrderedDeepMerge forlocal ./ _extends refsMerge layers + warnings(non-local refs warn, stay unmerged)Warnings on stderrMulti-document YAML on stdout(--layer N emits one layer)Cached entity: positional URIhery compose <entity-uri>ComposeEntity(uri)Paths()ReadAll(entity cache)Read every cached *.heryResolveExtendsChain+ DeepMerge per documentResolved documentsDeepMerge all into oneSingle merged documentYAML on stdout(or ./composed.hery when --print=false)Errorshery compose (no arg, no --dir)"entity argument required" + usage, exit 1--layer N beyond resolved layers:error on stderr, exit 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 @@ +hery compose — Flatten EntitiesUsercmd.entity.resolve.entity.compose.storage.entity.entity.merge.FilesystemUserUsercmd/cmd/entity/resolve/entity/resolve/entity/compose/entity/compose/storage/storage/entity/entity/entity/merge/entity/merge/FilesystemFilesystemLocal directory: --dirhery composedir <dir> [layer N]Resolve(dir)Read *.hery per directory(breadth-first over layers)Order documents by _requiresOrderedDeepMerge forlocal ./ _extends refsMerge layers + warnings(non-local refs warn, stay unmerged)Warnings on stderrMulti-document YAML on stdout(--layer N emits one layer)Cached entity: positional URIhery compose <entity-uri>ComposeEntity(uri)Paths()ReadAll(entity cache)Read every cached *.heryResolveExtendsChain+ DeepMerge per documentResolved documentsDeepMerge all into oneSingle merged documentYAML on stdout(or ./composed.hery when --print=false)Errorshery compose (no arg, no --dir)"entity argument required" + usage, exit 1--layer N beyond resolved layers:error on stderr, exit 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 @@ +hery entity — Subcommand DispatchUsercmd.entity.cmd.Usercmd/entity/cmd/Registration (process start)Register subcommands:init, get, list, valid(package init, before Execute)Dispatchhery entity <subcommand>Route to the subcommand's RunSubcommand outputBare invocationhery entityHelp text on stdout,exit 0Unknown subcommandhery entity bogusunknown command error+ usage on stderr, exit 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 @@ +hery entity get — Fetch Entities into the CacheUsercmd.entity.cmd.storage.entity.get.entity.build.entity.version.Git remoteentity.entity.merge.FilesystemUsercmd/entity/cmd/storage/entity/get/entity/build/entity/version/Git remoteentity/entity/merge/Filesystem(/.cache/hery/entity)Resolving versionshery entity get <uri>...GetCmd.RunPaths()(HERY_STORAGE_PATH or /.cache/hery)Get(paths, uris)Meta(uri) for each URIResolve versionList remote tagsTagsLatest tag, explicit @version,or pseudo-version from HEAD hashDownloadingMkdirAll <entities>/<uri>Clone repository(one goroutine per entity)Working treeCheckout tag(skipped for pseudo-versions)ReadAll(entity dir)Read every *.hery fileResolving referencesResolveExtendsChain per documentMeta for _extends / _type URIsFetch referenced entities(recursive clone)DeepMerge parent into childDone — silent on success(no SQLite writes)Fetch failureClone / unknown tag errorError on stderr, exit 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 @@ +hery entity get — Fetch Entities into the CacheUsercmd.entity.cmd.storage.entity.get.entity.build.entity.version.Git remoteentity.entity.merge.FilesystemUserUsercmd/cmd/entity/cmd/entity/cmd/storage/storage/entity/get/entity/get/entity/build/entity/build/entity/version/entity/version/Git remoteGit remoteentity/entity/entity/merge/entity/merge/Filesystem(/.cache/hery/entity)Filesystem(/.cache/hery/entity)Resolving versionshery entity get <uri>...GetCmd.RunPaths()(HERY_STORAGE_PATH or /.cache/hery)Get(paths, uris)Meta(uri) for each URIResolve versionList remote tagsTagsLatest tag, explicit @version,or pseudo-version from HEAD hashDownloadingMkdirAll <entities>/<uri>Clone repository(one goroutine per entity)Working treeCheckout tag(skipped for pseudo-versions)ReadAll(entity dir)Read every *.hery fileResolving referencesResolveExtendsChain per documentMeta for _extends / _type URIsFetch referenced entities(recursive clone)DeepMerge parent into childDone — silent on success(no SQLite writes)Fetch failureClone / unknown tag errorError on stderr, exit 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 @@ +hery entity init — Scaffold a New EntityUsercmd.entity.cmd.FilesystemUsercmd/entity/cmd/Filesystem(current dir)Scaffoldinghery entity init <entity-uri>InitCmd.RunDerive <name> from URI(basename, @version stripped)Write ./<name>.hery.json(JSON Schema draft 2020-12 stub,$id urn:hery:<uri>)Created ./<name>.hery.jsonWrite ./default.hery(_type: <uri>, empty _body)Created ./default.heryWrite failureWrite filePermission deniedError on stderr, exit 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 @@ +hery entity init — Scaffold a New EntityUsercmd.entity.cmd.FilesystemUserUsercmd/cmd/entity/cmd/entity/cmd/Filesystem(current dir)Filesystem(current dir)Scaffoldinghery entity init <entity-uri>InitCmd.RunDerive <name> from URI(basename, @version stripped)Write ./<name>.hery.json(JSON Schema draft 2020-12 stub,$id urn:hery:<uri>)Created ./<name>.hery.jsonWrite ./default.hery(_type: <uri>, empty _body)Created ./default.heryWrite failureWrite filePermission deniedError on stderr, exit 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 @@ +hery entity list — List Cached EntitiesUsercmd.entity.cmd.storage.entity.FilesystemUsercmd/entity/cmd/storage/entity/Filesystem(/.cache/hery/entity)Scanning the entity cachehery entity listListCmd.RunPaths()Entities dirCrawlDirectoriesParallel(dir)Walk + stat directories(10 parallel workers)Dirs matching <name>@<version>map of name to{origin, version}OutputEntity Origin | Entity Name | Versiontable on stdoutCache dir missingWalk errorError message printed,exit 0 \ 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 @@ +hery entity list — List Cached EntitiesUsercmd.entity.cmd.storage.entity.FilesystemUserUsercmd/cmd/entity/cmd/entity/cmd/storage/storage/entity/entity/Filesystem(/.cache/hery/entity)Filesystem(/.cache/hery/entity)Scanning the entity cachehery entity listListCmd.RunPaths()Entities dirCrawlDirectoriesParallel(dir)Walk + stat directories(10 parallel workers)Dirs matching <name>@<version>map of name to{origin, version}OutputEntity Origin | Entity Name | Versiontable on stdoutCache dir missingWalk errorError message printed,exit 0 \ 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 @@ +hery entity valid — Validate Cached EntitiesUsercmd.entity.cmd.storage.entity.entity.validation.entity.get.FilesystemUsercmd/entity/cmd/storage/entity/entity/validation/entity/get/FilesystemValidate everything: --allhery entity valid --allValidateCmd.RunPaths()CrawlDirectoriesParallel(entities dir)Walk entity cacheCached entitiesloop[each entity]ReadAll(entity path)Read *.hery documentsEntity(document)valid / validation failedPer-document result on stdoutFetch and inspect: --rm <uri>hery entity valid --rm <uri>ValidateCmd.RunGetInTmp(uris)TmpPaths()(mktemp hery_*)Full get flow:resolve, clone, read, mergeTemp entities dirTemp path printedNo argumentshery entity validHelp text, exit 0 \ 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 @@ +hery entity valid — Validate Cached EntitiesUsercmd.entity.cmd.storage.entity.entity.validation.entity.get.FilesystemUserUsercmd/cmd/entity/cmd/entity/cmd/storage/storage/entity/entity/entity/validation/entity/validation/entity/get/entity/get/FilesystemFilesystemValidate everything: --allhery entity valid --allValidateCmd.RunPaths()CrawlDirectoriesParallel(entities dir)Walk entity cacheCached entitiesloop[each entity]ReadAll(entity path)Read *.hery documentsEntity(document)valid / validation failedPer-document result on stdoutFetch and inspect: --rm <uri>hery entity valid --rm <uri>ValidateCmd.RunGetInTmp(uris)TmpPaths()(mktemp hery_*)Full get flow:resolve, clone, read, mergeTemp entities dirTemp path printedNo argumentshery entity validHelp text, exit 0 \ 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 @@ +hery entity — Subcommand DispatchUsercmd.entity.cmd.UserUsercmd/cmd/entity/cmd/entity/cmd/Registration (process start)Register subcommands:init, get, list, valid(package init, before Execute)Dispatchhery entity <subcommand>Route to the subcommand's RunSubcommand outputBare invocationhery entityHelp text on stdout,exit 0Unknown subcommandhery entity bogusunknown command error+ usage on stderr, exit 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 @@ +hery query — Two-Stage Entity QueryUsercmd.entity.query.cache.database.SQLiteentity.resolve.FilesystemUsercmd/entity/query/cache/database/SQLite(/.cache/hery/hery.db)entity/resolve/FilesystemStage 1 — selectionhery querytypemeta --tag[from |dir] [jq] [-o] [hery]alt[default source: cache]Open hery.db (WAL mode)Query(selection opts)SELECT merged_json FROM entitiesWHERE type GLOB / meta LIKE ...Read rowsmerged_json rows,decoded into documents[--from <file> or -]Open file (or stdin)LoadDocs — sniff JSON vsmulti-doc YAMLQueryDocs(selection opts)[--dir <dir>]Resolve(dir) into merge layersRead *.hery filesResolve warnings on stderrLoadDocs + QueryDocsover the layered docsStage 2 — transformationApplyJQToAll(--jq expression)Object results onlyOutputtable | json | yaml on stdout(--hery wraps in HERY envelope)exit 0, or exit 2 when no resultsErrors"hery query: <error>" on stderr, exit 1(missing cache db, bad --jq,from withdir) \ 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 @@ +hery query — Two-Stage Entity QueryUsercmd.entity.query.cache.database.SQLiteentity.resolve.FilesystemUserUsercmd/cmd/entity/query/entity/query/cache/database/cache/database/SQLite(/.cache/hery/hery.db)SQLite(/.cache/hery/hery.db)entity/resolve/entity/resolve/FilesystemFilesystemStage 1 — selectionhery querytypemeta --tag[from |dir] [jq] [-o] [hery]alt[default source: cache]Open hery.db (WAL mode)Query(selection opts)SELECT merged_json FROM entitiesWHERE type GLOB / meta LIKE ...Read rowsmerged_json rows,decoded into documents[--from <file> or -]Open file (or stdin)LoadDocs — sniff JSON vsmulti-doc YAMLQueryDocs(selection opts)[--dir <dir>]Resolve(dir) into merge layersRead *.hery filesResolve warnings on stderrLoadDocs + QueryDocsover the layered docsStage 2 — transformationApplyJQToAll(--jq expression)Object results onlyOutputtable | json | yaml on stdout(--hery wraps in HERY envelope)exit 0, or exit 2 when no resultsErrors"hery query: <error>" on stderr, exit 1(missing cache db, bad --jq,from withdir) \ 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 @@ +hery settings — Paths and EnvironmentUsercmd.storage.env.FilesystemUsercmd/storage/env/FilesystemResolving the storage roothery settingsMain()HERY_STORAGE_PATH if set,else user cache dir + /heryCollections pathCollecting env varsList()Parse env/types.go in thecurrent working directoryEnv var namesNamesos.Getenv for each nameOutputSetting | Value tableon stdoutOutside the source treeList()env/types.go not foundError on stderr, exit 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 @@ +hery settings — Paths and EnvironmentUsercmd.storage.env.FilesystemUserUsercmd/cmd/storage/storage/env/env/FilesystemFilesystemResolving the storage roothery settingsMain()HERY_STORAGE_PATH if set,else user cache dir + /heryCollections pathCollecting env varsList()Parse env/types.go in thecurrent working directoryEnv var namesNamesos.Getenv for each nameOutputSetting | Value tableon stdoutOutside the source treeList()env/types.go not foundError on stderr, exit 1 \ No newline at end of file From ee6ca29633546fd70c83169853989e9dd633868b Mon Sep 17 00:00:00 2001 From: jnbdz Date: Sun, 26 Jul 2026 21:00:13 -0400 Subject: [PATCH 11/11] Fix hery command table verb and diagram-page participant list --- docs/tools/hery-commands.md | 3 ++- docs/tools/hery.md | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/tools/hery-commands.md b/docs/tools/hery-commands.md index a5967f8..e22666a 100644 --- a/docs/tools/hery-commands.md +++ b/docs/tools/hery-commands.md @@ -6,7 +6,8 @@ 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). +`entity/` and `env/` where the code calls them directly, and the externals +they talk to (filesystem, Git remotes, SQLite). ## hery entity diff --git a/docs/tools/hery.md b/docs/tools/hery.md index 1fd684c..5869fcc 100644 --- a/docs/tools/hery.md +++ b/docs/tools/hery.md @@ -10,8 +10,9 @@ | 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 |