mneme-cli 0.5.0__tar.gz → 0.5.2__tar.gz

{mneme_cli-0.5.0 → mneme_cli-0.5.2}/AGENTS.md

@@ -213,6 +213,10 @@ out manually, then run `resync-resolve`.
 mneme tags suggest <client>/<page>                     # build tag packet
 mneme tags suggest <client>/<page> --json              # raw dict
 mneme tags apply <client>/<page> --add t1,t2 --remove t3
+
+# Bulk variants -- packet up to N pages in one round-trip
+mneme tags bulk-suggest --client <c> --filter req- --limit 50 --out packet.md
+mneme tags bulk-apply response.json     # response: {"pages": [{wiki_path, add, remove}, ...]}
 ```
 
 `mneme tags suggest` builds a **tag packet**: the page content, current
@@ -245,6 +249,124 @@ mneme tags list                                        # all tags + counts
 mneme tags merge <old> <new>                           # rename across all pages
 ```
 
+### 3.7 ENTITY — agent-driven classification
+
+```bash
+mneme entity suggest --client <c> --limit 50          # classification packet
+mneme entity apply --id iso-13485 --type standard     # one at a time
+mneme entity bulk-apply classifications.json          # batch
+```
+
+`mneme entity suggest` builds an **entity packet**: every `unknown`-typed
+entity, the workspace's current type distribution, the valid type
+vocabulary, an example wiki page per entity, and a prompt. The agent
+returns a JSON array of `{id, type}` objects which `bulk-apply` writes
+back atomically. Same philosophy as tags: mneme stays deterministic, the
+LLM does the classification.
+
+Valid types: `standard`, `company`, `person`, `product`, `technology`,
+`concept`, `brand`, `unknown`.
+
+### 3.8 HOME — generated landing page
+
+```bash
+mneme home --client <c>          # wiki/<c>/HOME.md
+mneme home --all-clients         # wiki/HOME.md (cross-client)
+```
+
+Generates an Obsidian-friendly navigation hub with Dataview queries
+(group by type, by ID prefix like `REQ-*` / `DDS-*`, top tags) and a
+plain-markdown `<details>` fallback so the page is useful outside
+Obsidian. Run after a large ingest, or whenever the wiki's shape
+changes meaningfully.
+
+### 3.9 TRACE — linking the full V-model chain
+
+The trace chain a notified body expects has two legs that both terminate
+at code and tests:
+
+```
+UN  ──implemented-by──┐
+                      ├──> REQ ──detailed-in──> DDS ──implemented-in──> codebase
+RMA ──mitigated-by────┘                             └──verified-by───> tests
+```
+
+The first three links (UN→REQ, RMA→REQ, REQ→DDS) are created
+automatically by the CSV mappings in `profiles/mappings/` (or by
+`mneme trace add` when ingesting structured sources). The last two
+links (DDS→codebase, DDS→tests) close the V-model and are the agent's
+responsibility when a user passes you one or more repositories.
+
+**When the user passes you a repo path, you must:**
+
+```bash
+# 1. Inventory: what code modules / test files exist?
+mneme scan-repo <repo-path> <client>
+# → reports which wiki pages reference the repo's modules, and which do not.
+
+# 2. For each DDS page that corresponds to a code module, add the link.
+#    The target is a git URL or an absolute repo path; mneme treats it
+#    as an opaque string (not a wiki slug) — the target may live outside
+#    the workspace.
+mneme trace add <client>/dds-cyb-001 \
+                "github.com/<org>/<repo>/blob/main/src/auth/password_policy.py" \
+                implemented-in
+
+# 3. For each DDS page that has a corresponding test, add the link.
+#    The test target can be a wiki page (for test-plan docs) or an
+#    external path (for a test file in a repo).
+mneme trace add <client>/dds-cyb-001 <client>/test-auth-001 verified-by
+mneme trace add <client>/dds-cyb-001 \
+                "github.com/<org>/<repo>/blob/main/tests/test_password_policy.py" \
+                verified-by
+```
+
+Do this for every DDS page that has implementing code or a verifying
+test. When there are tens or hundreds of links to create (typical for
+a real medical-device codebase):
+
+```bash
+# Batch approach — the agent parses the repo, maps DDS → files,
+# then writes a shell script of `mneme trace add` lines and runs it.
+# mneme has no bulk-trace-add subcommand yet; scripting is the way.
+for pair in dds-cyb-001:src/auth/password_policy.py \
+            dds-cyb-002:src/auth/mfa.py \
+            dds-cyb-003:src/auth/rate_limiter.py; do
+  dds=${pair%%:*}; file=${pair##*:}
+  mneme trace add <client>/$dds "<repo-url>/$file" implemented-in
+done
+```
+
+**Verify the chain is now complete:**
+
+```bash
+mneme trace gaps <client>
+# → should report 0 hazards without mitigation, 0 DDS without
+#   implementation link, 0 DDS without verification link
+
+mneme trace show <client>/un-001
+# → UN.001
+#     implemented-by -> REQ.SYS.001
+#         detailed-in -> DDS.CYB.001
+#             implemented-in -> github.com/.../password_policy.py
+#             verified-by    -> github.com/.../test_password_policy.py
+```
+
+**Relationship vocabulary — use exactly these strings:**
+
+| Relationship | From → To | Semantics |
+|---|---|---|
+| `implemented-by` | UN → REQ | The user need is met by this requirement |
+| `mitigated-by` | RMA → REQ | The hazard is mitigated by this requirement |
+| `derived-from` | REQ → UN / REQ → higher-level REQ | Parent requirement |
+| `detailed-in` | REQ → DDS | The requirement is elaborated by this design spec |
+| `implemented-in` | DDS → codebase | The design spec is realised by this source file / module |
+| `verified-by` | DDS → test / REQ → test | The spec/requirement is verified by this test |
+| `validated-by` | DDS → clinical/usability study | Validation (not verification) evidence |
+
+Stick to this vocabulary. Custom relationships confuse downstream
+matrix exports and break the default `trace gaps` heuristics.
+
 ---
 
 ## 4. Profiles and the writing-style contract
@@ -537,7 +659,53 @@ file.
 Stop conditions: inbox is empty, `mneme stats` shows a plausible page
 count, and `mneme lint` reports no critical issues.
 
-### 6.6 Pre-submission readiness check before sending to a notified body
+### 6.6 Close the V-model by linking DDS to codebase and tests
+
+The user has just handed you one or more repositories. Your job is to
+connect every DDS page to the implementing source file(s) and the
+verifying test file(s) so `mneme trace show` walks end-to-end from a
+user need / hazard all the way to the exact line of code and the exact
+test that exercises it.
+
+```
+1. mneme profile show                            # sanity check
+2. mneme trace matrix <client>                   # baseline — which DDS exist?
+3. For each repo the user passes:
+     a. mneme scan-repo <repo-path> <client>     # surface module gaps
+     b. Read the repo tree and README yourself.
+        Build a mapping: DDS ID -> [source files]
+                         DDS ID -> [test files]
+        Prefer explicit evidence (comments referencing the DDS ID,
+        module/function names that mirror the DDS title, docstrings
+        that cite the requirement). When evidence is weak, flag the
+        DDS as ambiguous and surface it — do not guess.
+4. For each confident (DDS, file) pair:
+     mneme trace add <client>/<dds-slug> "<repo-url-or-path>/<file>" implemented-in
+     mneme trace add <client>/<dds-slug> "<repo-url-or-path>/<test-file>" verified-by
+   Batch these in a shell loop — there is no bulk-trace-add subcommand.
+5. mneme trace gaps <client>                     # should trend to zero
+6. mneme trace show <client>/un-001              # spot-check: full chain
+                                                   from UN to test file?
+7. mneme trace matrix <client> --csv --out trace-matrix.csv
+                                                 # DHF-ready export
+```
+
+Stop conditions: (a) every DDS page either has both `implemented-in`
+and `verified-by` trace links OR is explicitly flagged ambiguous in a
+report to the user, AND (b) `trace gaps` reports zero open chains.
+
+Hard rules:
+- Do not fabricate file paths. If the repo has no file matching a DDS,
+  report the gap and stop — the user must either point you at another
+  repo or add the link manually.
+- Trace targets for external files are opaque strings. Use a stable
+  form the team can resolve later (a git URL with a pinned commit is
+  ideal; a bare relative path is fine when the repo lives alongside
+  the workspace).
+- Never rewrite a DDS page's body to embed the code link. The link
+  lives in `schema/traceability.json` only. Wiki pages stay prose.
+
+### 6.7 Pre-submission readiness check before sending to a notified body
 
 ```
 1. mneme profile show                            # confirm active profile

{mneme_cli-0.5.0 → mneme_cli-0.5.2}/CHANGELOG.md

@@ -4,6 +4,51 @@ All notable changes to this project are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.2] - 2026-04-14
+
+### Changed
+
+- **`ingest-dir --preserve-structure` is now the default.** The wiki now
+  mirrors the source directory layout unless you pass `--flat`. This avoids
+  silent same-basename collisions (e.g. multiple `INSTRUCTIONS.md` files from
+  different source directories overwriting each other). Closes suggestion #15.
+- **`mneme ingest` (single-file) also mirrors by default.** When the source
+  lives under `sources/<client>/`, its relative position becomes a wiki
+  subpath automatically. Pass `--flat` to opt out.
+
+### Fixed
+
+- **`mneme profile list`** now discovers profiles correctly. Previously it
+  filtered files by `.json` (wrong extension — profiles are markdown) and
+  only checked the bundled directory, which meant the shipped `eu-mdr.md`
+  and `iso-13485.md` profiles appeared as "No profiles found". Now unions
+  workspace + bundled, marks origin, and flags shadowed bundled profiles.
+  Closes suggestion #25 discovery bug.
+
+### Added
+
+- **`ingest-dir --flat`** — explicit opt-out for the new preserve-structure
+  default.
+- **`ingest --flat`** — opt-out for the single-file command.
+- **xlsx support is now built-in.** `openpyxl` moved from
+  `[project.optional-dependencies].xlsx` to `dependencies`. The `[xlsx]`
+  extra is kept for backwards compatibility but is no longer required.
+
+### Documentation
+
+- **README**: expanded the agent end-to-end example. Step 3 now covers
+  bulk tagging (`tags bulk-suggest` + `bulk-apply`), Step 3b adds entity
+  typing (`entity suggest` + `bulk-apply`), and Step 3c walks the full
+  V-model trace chain (UN→REQ→DDS and RMA→REQ→DDS, terminating at code
+  and tests).
+- **AGENTS.md**: new section 3.9 "TRACE — linking the full V-model
+  chain" documents the `implemented-in` / `verified-by` relationships
+  and the DDS-to-codebase linking agents must perform when the user
+  passes repositories. New task template 6.6 "Close the V-model by
+  linking DDS to codebase and tests" gives the exact procedure, stop
+  conditions, and hard rules (no fabricated paths, trace targets are
+  opaque strings, never embed code links in page bodies).
+
 ## [0.5.0] - 2026-04-13
 
 ### Breaking Changes
@@ -58,6 +103,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Chunking logic (`chunk_body`, `MAX_CHUNK_SIZE`, frame management).
 - Tantivy-reserved-word query sanitizer (FTS5 has different syntax).
 
+## [0.5.1] - 2026-04-14
+
+### Added
+- **`mneme entity suggest` / `entity apply` / `entity bulk-apply`** — agent-driven
+  entity classification (same packet pattern as `tags suggest`). Mneme builds a
+  packet of unclassified entities + the workspace type taxonomy + example pages;
+  the LLM agent classifies; mneme writes the types back atomically.
+- **`mneme tags bulk-suggest` / `tags bulk-apply`** — operate on many pages at
+  once. `bulk-suggest --client X --filter req- --limit 50` packets up to 50
+  matching pages; agent returns one JSON file; `bulk-apply` runs all the changes
+  with per-page error tolerance. Critical for tagging workspaces of hundreds of
+  pages.
+- **`mneme home --client <slug>` / `--all-clients`** — generates a `HOME.md`
+  navigation hub with Obsidian Dataview queries (group by type, by ID prefix
+  like REQ-*/DDS-*, top tags) plus a plain-markdown `<details>` fallback for
+  non-Obsidian viewers.
+- **`mneme ingest-dir --preserve-structure`** — mirrors source directory
+  hierarchy into wiki subdirectories. `sources/client/REQUIREMENTS/req-001.md`
+  becomes `wiki/client/requirements/req-001.md` instead of flattening. Also
+  resolves same-basename-different-directory collisions naturally.
+- **`mneme resync` auto-detects subpath** from a source's location under
+  `sources/<client>/`, so resyncs of preserve-structure ingests target the
+  correct nested wiki page instead of creating a duplicate flat one.
+- **Progress bar** for `ingest-dir` and `ingest-csv` long loops. TTY-aware
+  (in-place updates) with non-TTY fallback (periodic line output) so CI logs
+  stay readable.
+
+### Fixed
+- `mneme status` crashed with `UnboundLocalError` because a local `status` in
+  the `agent show` branch shadowed the function name throughout `main()`.
+- `wiki/HOME.md` and `wiki/<client>/HOME.md` are now skipped during HOME
+  generation so re-running is idempotent.
+
 ## [Unreleased]
 
 ### Added

{mneme_cli-0.5.0 → mneme_cli-0.5.2}/CLAUDE.md

@@ -1,4 +1,4 @@
-# Mnemosyne - Wiki Protocol
+# mneme - Wiki Protocol
 
 > **If you are an LLM agent driving mneme**, read [AGENTS.md](AGENTS.md) **first**. It is the canonical agent protocol: the agent loop, the standard task templates, the sub-agent spawning patterns, and the hard rules you must never violate. CLAUDE.md (this file) describes the wiki layer; AGENTS.md describes the agent's job.
 

{mneme_cli-0.5.0 → mneme_cli-0.5.2}/CODER.md

@@ -1,4 +1,4 @@
-# CODER.md - Developer Guide for Mnemosyne
+# CODER.md - Developer Guide for mneme
 
 This is the engineering reference for anyone building on or extending mneme. Read this before writing code.
 

{mneme_cli-0.5.0 → mneme_cli-0.5.2}/EXAMPLES.md

@@ -1,4 +1,4 @@
-# EXAMPLES.md - Mnemosyne Usage Guide
+# EXAMPLES.md - mneme Usage Guide
 
 Real-world workflows, core concepts, and entity types used in mneme.
 
@@ -256,7 +256,7 @@ cp ~/old-qms/*.pdf inbox/
 # Let tornado figure it out
 mneme tornado --client cardio-monitor
 
-#   === Mnemosyne Tornado ===
+#   === mneme Tornado ===
 #
 #   Scanning inbox/... found 50 files
 #

{mneme_cli-0.5.0 → mneme_cli-0.5.2}/FEATURES.md

@@ -1,4 +1,4 @@
-# Mnemosyne - Feature Roadmap
+# mneme - Feature Roadmap
 
 ## Current Features (v0.4.0)
 
@@ -34,6 +34,13 @@
 | `mneme tags merge` | Merge one tag into another across all pages |
 | `mneme tags suggest <page>` | Build a *tag packet* for an LLM agent (page content + taxonomy + prompt) |
 | `mneme tags apply <page> --add t1,t2 --remove t3` | Atomic tag update: rewrites frontmatter, updates schema/tags.json, re-syncs FTS5 index |
+| `mneme tags bulk-suggest --client X --filter req- --limit 50` | Bulk tag packet for many pages in one round-trip |
+| `mneme tags bulk-apply response.json` | Apply tag changes from an agent JSON response (per-page error tolerance) |
+| `mneme entity suggest --client X` | Agent-driven entity-classification packet (entities + taxonomy + example pages) |
+| `mneme entity apply --id <id> --type <type>` | Set one entity's type atomically |
+| `mneme entity bulk-apply classifications.json` | Bulk classify entities from a JSON file |
+| `mneme home --client X` / `--all-clients` | Generate a `HOME.md` navigation hub with Dataview queries and plain-markdown fallback |
+| `mneme ingest-dir --preserve-structure` | Mirror source directory hierarchy into wiki subdirectories (resync auto-detects matching subpath) |
 | `mneme diff` | Git-aware diff for a wiki page |
 | `mneme snapshot` | Versioned zip archive of a client + git tag |
 | `mneme dedupe` | Detect near-duplicate wiki pages |

{mneme_cli-0.5.0 → mneme_cli-0.5.2}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: mneme-cli
-Version: 0.5.0
-Summary: Mnemosyne - CLI tool that turns documents into a searchable second brain. Ingest once, query forever.
+Version: 0.5.2
+Summary: mneme - CLI tool that turns documents into a searchable second brain. Ingest once, query forever.
 Author-email: Tolis Moustaklis <apostolos.moustaklis@gmail.com>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/tolism/mneme
@@ -29,20 +29,20 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: portalocker>=2.0.0
+Requires-Dist: openpyxl>=3.1.0
 Provides-Extra: pdf
 Requires-Dist: pymupdf>=1.23.0; extra == "pdf"
 Provides-Extra: xlsx
 Requires-Dist: openpyxl>=3.1.0; extra == "xlsx"
 Provides-Extra: all
 Requires-Dist: pymupdf>=1.23.0; extra == "all"
-Requires-Dist: openpyxl>=3.1.0; extra == "all"
 Provides-Extra: release
 Requires-Dist: build>=1.0.0; extra == "release"
 Requires-Dist: twine>=5.0.0; extra == "release"
 Dynamic: license-file
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/tolism/mneme/main/assets/logo.png" alt="Mnemosyne" width="400">
+  <img src="https://raw.githubusercontent.com/tolism/mneme/main/assets/logo.png" alt="mneme" width="400">
 </p>
 
 <h1 align="center"></h1>
@@ -167,6 +167,13 @@ One installed CLI serves many projects — each workspace is just a directory.
 | `mneme validate writing-style <page>` | Build a *review packet* for an LLM agent to grade a page |
 | `mneme tags suggest <page>` | Build a *tag packet* for an LLM agent to choose tags |
 | `mneme tags apply <page> --add t1,t2 --remove t3` | Atomic tag update (frontmatter + schema + search index) |
+| `mneme tags bulk-suggest --client X --filter req- --limit 50` | Build one *bulk packet* covering many pages |
+| `mneme tags bulk-apply response.json` | Apply tag changes from an agent JSON response |
+| `mneme entity suggest --client X` | Build an *entity-classification packet* for an LLM agent |
+| `mneme entity apply --id <id> --type <type>` | Set one entity's type atomically |
+| `mneme entity bulk-apply classifications.json` | Bulk classify many entities |
+| `mneme home --client X` / `--all-clients` | Generate a `HOME.md` navigation hub (Dataview + fallback) |
+| `mneme ingest-dir --recursive --preserve-structure` | Mirror source directory hierarchy into the wiki |
 | `mneme agent plan --goal "..." --doc-type <t> --client <c>` | Generate a deterministic TODO plan from the active profile |
 | `mneme agent next-task` | Return the next ready task in the active plan |
 | `mneme agent task-done <id>` | Mark a task as done |
@@ -176,7 +183,7 @@ One installed CLI serves many projects — each workspace is just a directory.
 | `mneme stats` | Health overview |
 | `mneme repair` | Fix corrupted archives |
 
-**Formats:** `.md`, `.txt`, `.pdf`, `.xlsx` (with `pip install "mneme-cli[xlsx]"`)
+**Formats:** `.md`, `.txt`, `.pdf`, `.xlsx` (built-in), plus `.csv` via `mneme ingest-csv`
 
 ---
 
@@ -231,38 +238,115 @@ Creates the workspace tree, sets the EU MDR writing-style profile, and initializ
 cp -r ~/Downloads/parkinson-research/* inbox/
 mneme tornado --client parkiwatch
 
-# Or ingest individual files
+# Or ingest individual files (auto-mirrors sources/<client>/ layout into wiki/)
 mneme ingest research-paper.pdf parkiwatch
-mneme ingest-csv risk-register.csv parkiwatch --mapping risk-register
 mneme ingest spec-table.xlsx parkiwatch          # .xlsx renders sheets as markdown tables
-mneme ingest-dir docs/ parkiwatch --recursive    # walk subdirectories
+mneme ingest-dir docs/ parkiwatch --recursive    # walk subdirectories, preserve structure
+
+# Structured CSV ingestion — one row becomes one wiki page + trace links.
+# Mappings live in <workspace>/profiles/mappings/ or are auto-detected.
+mneme ingest-csv user-needs.csv    parkiwatch --mapping parkiwatch-user-needs
+mneme ingest-csv requirements.csv  parkiwatch --mapping parkiwatch-req
+mneme ingest-csv design-specs.csv  parkiwatch --mapping parkiwatch-dds
+mneme ingest-csv risk-register.csv parkiwatch --mapping parkiwatch-rma
 ```
 
-What happens per ingest: source file → wiki page in `wiki/parkiwatch/` → frontmatter with auto-extracted entities → entry in `index.md` → row in the FTS5 search DB → log entry.
+What happens per ingest: source file → wiki page in `wiki/parkiwatch/<mirrored-subpath>/` → frontmatter with auto-extracted proper-noun entities → entry in `index.md` → row in the FTS5 search DB → log entry. CSV ingests additionally create trace links (e.g. UN→REQ `implemented-by`, REQ→DDS `detailed-in`) in `schema/traceability.json`.
 
-### Step 3 — Tag the new pages (LLM agent)
+### Step 3 — Tag many pages at once (LLM agent, bulk)
 
-The new pages have only the auto-applied `parkiwatch` client tag. The agent now adds meaningful tags:
+New pages have only the auto-applied `parkiwatch` client tag. The agent tags them in batches:
 
 ```bash
-# For each new page, the agent runs:
-mneme tags suggest parkiwatch/research-paper > /tmp/packet.md
+# 1. Pack up to 30 untagged pages into a single review packet.
+#    --filter scopes by wiki_path substring; omit for everything.
+mneme tags bulk-suggest --filter indicators --limit 30 \
+                        --json --out /tmp/tag-packet.json
 ```
 
-The packet contains the page body, the current tag taxonomy (every tag in the workspace + usage counts), and a ready-to-paste prompt. **The LLM reads the packet** — it understands the content and decides on tags, preferring existing taxonomy entries when they fit. The LLM's response is JSON:
+The packet contains, for each page: wiki_path, title, current tags, body excerpt, and the existing taxonomy with usage counts. **The LLM reads the packet** and returns a response JSON:
 
 ```json
-{"tags": ["clinical-trial", "iso-13485"], "new_tags": ["bradykinesia-detection"]}
+{
+  "pages": [
+    {"wiki_path": "parkiwatch/indicators/bda_algorithm_description.md",
+     "add": ["bradykinesia", "algorithm", "imu", "medical-device"]},
+    {"wiki_path": "parkiwatch/indicators/tremor_indicator_dataflow.md",
+     "add": ["tremor", "dataflow", "imu", "algorithm"]}
+  ]
+}
 ```
 
-The agent then runs:
+```bash
+# 2. Apply all decisions in one atomic call
+mneme tags bulk-apply /tmp/tag-response.json
+# → Pages updated: 9   Tags added: 42   Tags removed: 0
+```
+
+Each application rewrites the wiki page frontmatter, updates `schema/tags.json`, re-indexes the page in FTS5, and appends a log entry. Subsequent packets reuse the growing taxonomy, so the vocabulary converges.
+
+For single pages use `mneme tags suggest <slug>` + `mneme tags apply <slug> --add a,b,c`.
+
+### Step 3b — Classify entities by type (LLM agent)
+
+Ingest auto-extracts capitalized proper nouns (e.g. "Parkiwatch", "IEC 62304") into `schema/entities.json` with `type: unknown`. Typing is an LLM judgement call, handled the same packet way as tags:
 
 ```bash
-mneme tags apply parkiwatch/research-paper \
-  --add clinical-trial,iso-13485,bradykinesia-detection
+# 1. Build an entity-classification packet (up to 50 unclassified entities)
+mneme entity suggest --client parkiwatch --limit 50 \
+                     --json --out /tmp/entity-packet.json
+
+# 2. LLM reads the packet and returns classifications:
+#    [{"id": "iec-62304", "type": "standard"},
+#     {"id": "notified-body", "type": "organization"},
+#     {"id": "bradykinesia", "type": "concept"}, ...]
+
+# 3. Apply atomically
+mneme entity bulk-apply /tmp/entity-response.json
+# → Entities typed: 47   Errors: 0
+```
+
+Supported types include `standard`, `organization`, `person`, `concept`, `technology`, `regulation`, or any custom type the profile defines. Typed entities power filtered search and the knowledge graph.
+
+### Step 3c — Verify the trace chain (human, on demand)
+
+The CSV ingests in Step 2 created two parallel trace chains. Both converge at a requirement, drill into design specs, and finally terminate at **code** and **tests** — the complete QMS traceability an auditor expects:
+
+```
+Chain A:  UN ─┐
+              ├─> REQ ──> DDS ──┬─> codebase  (via `implemented-in`)
+Chain B:  RMA ┘                 └─> tests     (via `verified-by`)
 ```
 
-Atomic operation: rewrites the wiki page frontmatter, updates `schema/tags.json`, re-indexes the page in FTS5 (so search picks up the new tags immediately), appends a log entry. **Repeat for every page** — the taxonomy grows, and subsequent pages tend to reuse existing tags (consistency).
+Each arrow is a trace-link relationship type (`implemented-by`, `mitigated-by`, `detailed-in`, `implemented-in`, `verified-by`). The DDS→codebase link is stored as a frontmatter field on each DDS page (e.g. a git URL pointing at the implementing module). The DDS→tests link is a standard trace relationship added either by CSV ingest or by `mneme trace add`.
+
+Walk either chain from any root page:
+
+```bash
+# Chain A — from a user need forward to the specs that implement it
+mneme trace show parkiwatch/un-001
+# → UN.001 (secure sign-in)
+#     implemented-by -> REQ.SYS.001 (User Authentication)
+#         detailed-in -> DDS.CYB.001 (Strong Password Policy)
+#         detailed-in -> DDS.CYB.002 (Multi-Factor Authentication)
+#         ...
+
+# Chain B — from a hazard forward to the specs that mitigate it
+mneme trace show parkiwatch/rma-cyb-002
+# → RMA.CYB.002 (Unauthorized access -- weak passwords)
+#     mitigated-by -> REQ.SYS.001 (User Authentication)
+#         detailed-in -> DDS.CYB.001, DDS.CYB.002, ...
+#             implemented-in -> src/auth/password_policy.py   (codebase)
+#             verified-by    -> TEST.AUTH.001                 (tests)
+
+# Trace gaps for a notified body audit
+mneme trace gaps parkiwatch
+# → Hazards with no mitigation: ...
+#   User needs with no requirements: ...
+
+# Export the full traceability matrix for the DHF
+mneme trace matrix parkiwatch --csv --out trace-matrix.csv
+```
 
 ### Step 4 — Search the knowledge base (anyone)