narrativetrace 0.1.2__tar.gz → 0.2.0__tar.gz

{narrativetrace-0.1.2 → narrativetrace-0.2.0}/.gitignore

@@ -1,6 +1,7 @@
 __pycache__/
 *.py[cod]
 .venv/
+.venv-host/
 .pytest_cache/
 .mypy_cache/
 .ruff_cache/

{narrativetrace-0.1.2 → narrativetrace-0.2.0}/LICENSE

@@ -7,7 +7,7 @@ Parameters
 
 Licensor:             Empower Agile
 
-Licensed Work:        NarrativeTrace for Python (the narrativetrace PyPI distributions) version 0.1.2. The Licensed Work is (c) 2026 Empower Agile.
+Licensed Work:        NarrativeTrace for Python (the narrativetrace PyPI distributions) version 0.2.0. The Licensed Work is (c) 2026 Empower Agile.
 
 Additional Use Grant: You may make production use of the Licensed Work for any
                       purpose, including internal use and use in products and
@@ -18,7 +18,7 @@ Additional Use Grant: You may make production use of the Licensed Work for any
                       parties as a logging, tracing, or code-narrative product
                       or service.
 
-Change Date:          Four years from the date the Licensed Work is published. (2030-09-16 for this version)
+Change Date:          Four years from the date the Licensed Work is published. (2030-10-05 for this version)
 
 Change License:       Apache License, Version 2.0
 

{narrativetrace-0.1.2 → narrativetrace-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: narrativetrace
-Version: 0.1.2
+Version: 0.2.0
 Summary: Narrative execution tracing for Python — human- and LLM-readable traces
 Project-URL: Homepage, https://github.com/narrativetrace/narrativetrace-python
 Project-URL: Source, https://github.com/narrativetrace/narrativetrace-python
@@ -12,11 +12,13 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
+Requires-Dist: narrativetrace-tooling
 Description-Content-Type: text/markdown
 
 # narrativetrace
 
-Human- and LLM-readable narrative execution tracing for Python. Dependency-free core.
+Human- and LLM-readable narrative execution tracing for Python. The core, with no third-party
+dependencies.
 
 Part of the [narrativetrace](../../README.md) workspace. The
 [Feature Guide](../../documentation/feature-guide.md) carries scope and status.

{narrativetrace-0.1.2 → narrativetrace-0.2.0}/README.md

@@ -1,6 +1,7 @@
 # narrativetrace
 
-Human- and LLM-readable narrative execution tracing for Python. Dependency-free core.
+Human- and LLM-readable narrative execution tracing for Python. The core, with no third-party
+dependencies.
 
 Part of the [narrativetrace](../../README.md) workspace. The
 [Feature Guide](../../documentation/feature-guide.md) carries scope and status.

{narrativetrace-0.1.2 → narrativetrace-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "narrativetrace"
-version = "0.1.2"
+version = "0.2.0"
 description = "Narrative execution tracing for Python — human- and LLM-readable traces"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -16,7 +16,11 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Typing :: Typed",
 ]
-dependencies = []
+# One dependency, and it carries no further ones: narrativetrace-tooling is this family's own
+# standard-library-only library (its architecture test pins that), holding the doctor's checks and
+# the agent-skills installer behind the `narrativetrace` console script declared below. No
+# third-party code reaches a consumer's environment through this distribution.
+dependencies = ["narrativetrace-tooling"]
 
 [project.urls]
 Homepage = "https://github.com/narrativetrace/narrativetrace-python"
@@ -41,7 +45,14 @@ packages = ["src/narrativetrace"]
 [tool.mutmut]
 source_paths = ["src/narrativetrace/"]
 also_copy = ["tests/"]
-pytest_add_cli_args_test_selection = ["tests/"]
+# "not distribution" deselects the tests marked `distribution`: they build real wheels/sdists via
+# `uv build`, which an offline mutation run cannot do once its build backend is not already
+# cached -- a distribution test proves packaging, not code under mutation, and has no place in
+# this baseline (it still runs in the ordinary test suite). "not stress" is restated here, not
+# just "not distribution" added, because pytest keeps only the LAST -m it sees rather than
+# combining several -m flags -- a bare "not distribution" here would silently override the root
+# addopts' own "not stress" and let the concurrency stress suite back into every mutation run.
+pytest_add_cli_args_test_selection = ["tests/", "-m", "not stress and not distribution"]
 # The plugin distribution imports narrativetrace at plugin-load time, before the mutated copy is on
 # sys.path — loading it would test the installed package instead of the mutant.
 pytest_add_cli_args = ["-p", "no:narrativetrace"]

{narrativetrace-0.1.2 → narrativetrace-0.2.0}/src/narrativetrace/__init__.py

@@ -97,7 +97,7 @@ from narrativetrace.values import (
     StringVal,
 )
 
-__version__ = "0.1.2"
+__version__ = "0.2.0"
 
 __all__ = [
     "NOOP_CONTEXT",

narrativetrace-0.2.0/src/narrativetrace/_skills/agents/add-narrative-tracing/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: add-narrative-tracing
+description: "Installs NarrativeTrace into a Python project and gets it to a first trace. Use when NarrativeTrace is not yet installed, a project needs its very first traced call, or traces need to reach a real logger instead of bare print statements. Installs narrativetrace with uv add, wraps an object with trace_object, renders and runs the first trace, then wires the stdlib logging bridge so traces reach your logger. Runs narrativetrace doctor to confirm the install is correctly wired -- narrativetrace-doctor owns diagnosis from there -- and previews the agent-skills install so the next session finds them. Say 'add narrative tracing to my service', 'install narrativetrace', 'get a trace in 60 seconds', 'wrap this object so I can see a trace', or 'send my traces to my logger' to invoke it."
+---
+
+# add-narrative-tracing
+
+## 1. Install with the real toolchain
+
+```bash
+uv sync --all-packages
+```
+
+**verify:** `uv run narrativetrace doctor --json | uv run python -c 'import json, sys
+report = json.load(sys.stdin)
+bad = [f for f in report["findings"] if f["id"].startswith("toolchain.") and f["status"] != "pass"]
+if bad:
+    print(json.dumps(bad))
+sys.exit(1 if bad else 0)
+'`
+
+**failure:** a sibling narrativetrace-* package disagrees on version — an installed distribution outside the lockstep version the other narrativetrace-* packages share. Fix: run the narrativetrace-doctor skill's toolchain.package-versions check, then pin every narrativetrace-* dependency to the same version and `uv sync`
+
+## 2. First trace: wrap, call, render, run
+
+<!-- snippet: examples/sixty_seconds/main.py -->
+```python
+# main.py
+from narrativetrace import ContextVarNarrativeContext, IndentedTextRenderer, TraceId, trace_object
+
+
+class OrderService:
+    def place_order(self, customer_id, product_id, quantity):
+        return f"ORD-{customer_id}-{product_id}-{quantity}"
+
+
+# snippet:begin fixedTraceId
+# A fixed trace id, adopted so this page's embedded output always names the same trace. A real
+# run generates a random one every time (never this -- it is this DEMO's own constant, not the
+# library default) via the same TraceId.adopt_trace_id a servlet-style boundary uses for an
+# inbound trace header.
+DEMO_TRACE_ID = TraceId("a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4")
+
+# snippet:end fixedTraceId
+
+context = ContextVarNarrativeContext()
+context.adopt_trace_id(DEMO_TRACE_ID)
+service = trace_object(OrderService(), context)
+service.place_order("cust-1", "prod-42", 3)
+
+print(IndentedTextRenderer().render(context.capture_trace()))
+```
+<!-- /snippet -->
+
+**verify:** `uv run python main.py`
+
+**failure:** a *args method's parameters render as one args: [...] value — inspect.signature has nothing named to reconstruct per-argument that Python itself does not have. Fix: supply explicit names: @traced("first", "second", ...) above the method
+
+## 3. Send it to your logger
+
+<!-- snippet: examples/sixty_seconds/main_with_logger.py -->
+```python
+# main.py
+import logging  # new: stdlib logging -- the sink this step sends the trace to
+import sys  # new: stdout target for the handler below
+
+from narrativetrace import (
+    ContextVarNarrativeContext,
+    IndentedTextRenderer,
+    NarrativeContextFilter,  # new: injects traceName/runName onto every log record
+    TraceId,
+    export_to_logger,  # new: replays an already-captured trace through your logger, one call
+    trace_object,
+)
+
+
+class OrderService:
+    def place_order(self, customer_id, product_id, quantity):
+        return f"ORD-{customer_id}-{product_id}-{quantity}"
+
+
+# snippet:begin fixedTraceId
+# A fixed trace id, adopted so this page's embedded output always names the same trace. A real
+# run generates a random one every time (never this -- it is this DEMO's own constant, not the
+# library default) via the same TraceId.adopt_trace_id a servlet-style boundary uses for an
+# inbound trace header.
+DEMO_TRACE_ID = TraceId("a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4")
+
+# snippet:end fixedTraceId
+
+# new: a plain stdlib logging setup -- the shape a real app's own logging config already has
+handler = logging.StreamHandler(sys.stdout)
+handler.addFilter(NarrativeContextFilter())  # new: makes traceName/runName available below
+# new: DEBUG so export_to_logger's records pass the handler; the format reads the filter's keys
+logging.basicConfig(
+    level=logging.DEBUG, format="[%(traceName)s] [%(runName)s] %(message)s", handlers=[handler]
+)
+
+context = ContextVarNarrativeContext()
+context.adopt_trace_id(DEMO_TRACE_ID)
+service = trace_object(OrderService(), context)
+service.place_order("cust-1", "prod-42", 3)
+
+trace = context.capture_trace()  # new: capture once, reuse for both the print and the export
+print(IndentedTextRenderer().render(trace))
+
+export_to_logger(trace)  # new: sends the same captured trace through the configured logger
+```
+<!-- /snippet -->
+
+**verify:** `uv run python main_with_logger.py`
+
+## 4. Run the doctor and resolve its findings
+
+```bash
+uv run narrativetrace doctor || true
+```
+
+**verify:** `uv run narrativetrace doctor --json | uv run python -c 'import json, sys
+report = json.load(sys.stdin)
+findings = report.get("findings")
+sys.exit(1 if not isinstance(findings, list) or len(findings) != 12 else 0)
+'`
+
+## 5. Install the skills for next time
+
+```bash
+uv run narrativetrace init --dry-run
+```
+
+**verify:** `uv run python -c 'import pathlib, subprocess, sys
+result = subprocess.run(
+    ["uv", "run", "narrativetrace", "init", "--dry-run"], capture_output=True, text=True
+)
+shown = (
+    "action(s)" in result.stdout
+    and ".agents/skills" in result.stdout
+    and "AGENTS.md" in result.stdout
+)
+untouched = not pathlib.Path(".agents/skills").exists() and not pathlib.Path("AGENTS.md").exists()
+sys.exit(0 if result.returncode == 0 and shown and untouched else 1)
+'`
+
+**failure:** the command exits 1 with no carrier resolved — no narrativetrace-skills distribution is installed and this project's own narrativetrace bundles no reachable fallback. Fix: run `uv add narrativetrace-skills`, or point --from at a local carrier directory or wheel
+
+## Always
+
+- Reinstall clean (`uv sync`) rather than trusting whatever is already in the virtual environment. (a mismatched sibling version or a stale lockfile is the single most common install failure, and it only surfaces on a clean install)
+
+## Never
+
+- Never assume a step worked without running its verify. (self-reported success overstates reality -- a build claimed green that does not reproduce from clean is not evidence)
+- Never skip the final narrativetrace doctor call. (it is the seam that catches anything these four steps did not -- narrativetrace-doctor owns diagnosis from here)
+- Never apply the installer without showing its diff first. (it writes into AGENTS.md and the project's skill directories, and the approval for that is a person reading the diff -- run it with --dry-run, show the output, and let them run it again without the flag)

narrativetrace-0.2.0/src/narrativetrace/_skills/agents/narrativetrace-doctor/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: narrativetrace-doctor
+description: "Diagnoses a NarrativeTrace Python install and configuration. Use when nothing is being traced, no trace output files appear, DuplicateConfigurationError shows up on startup, a *args method's parameters render as one args: [...] value, or you are not sure NarrativeTrace is wired up correctly. Checks the interpreter and pytest versions, that all eight narrativetrace-* packages agree on one version, NARRATIVETRACE_OUTPUT, that the pytest plugin is registered and not disabled, whether the NarrativeTrace agent skills are installed and current, unrecognized narrativetrace.toml keys, an imported-but-unused not_traced_field/__nt_not_traced__ marker, whether redaction is proven in a test, and stale approval-trace diffs. Read-only -- makes no changes. Say 'check my narrativetrace setup', 'is narrativetrace broken', or 'why isn't anything being traced' to invoke it."
+---
+
+# narrativetrace-doctor
+
+## 1. Run the doctor and read its report
+
+```bash
+uv run narrativetrace doctor || true
+```
+
+**verify:** `uv run narrativetrace doctor --json | uv run python -c 'import json, sys
+report = json.load(sys.stdin)
+findings = report.get("findings")
+sys.exit(1 if not isinstance(findings, list) or len(findings) != 12 else 0)
+'`
+
+**failure:** the CLI's JSON output does not parse, or is missing findings — the CLI crashed instead of reporting a finding. Fix: re-run `uv run narrativetrace doctor --json` directly and read the raw output -- a crash here is a doctor bug, never a project finding
+
+## 2. Prove redaction in a test
+
+```bash
+uv run python -c 'print(
+    "Render a call with a deny-listed parameter name (e.g. password or token) in a test and "
+    "assert the output contains [REDACTED], and that a neighboring non-sensitive value is still "
+    "present."
+)
+'
+```
+
+**verify:** `uv run narrativetrace doctor --json | uv run python -c 'import json, sys
+report = json.load(sys.stdin)
+by_id = {f["id"]: f for f in report["findings"]}
+finding = by_id.get("trap.redaction-proof")
+sys.exit(1 if finding is None or finding["status"] not in ("pass", "fail") else 0)
+'`
+
+**failure:** not_traced_field/__nt_not_traced__ is present but never applied — trusting redaction by inspection instead of proving it in a test. Fix: render a call with a deny-listed parameter name and assert the output contains "[REDACTED]"
+
+## 3. Read the rendered trace before asserting
+
+```bash
+uv run python -c 'import pathlib
+root = pathlib.Path("narrative-traces")
+files = sorted(root.rglob("*.md"), key=lambda p: p.stat().st_mtime) if root.is_dir() else []
+if not files:
+    print("no rendered .md file found yet under narrative-traces -- run your tests or app once")
+else:
+    newest = files[-1]
+    print(newest)
+    print(newest.read_text(encoding="utf-8"))
+'
+```
+
+## 4. Approval flow: diff the structural trace, not just values
+
+**Flagged:** unstudied -- eval cell pending
+
+```bash
+uv run python -c 'import pathlib
+root = pathlib.Path("test-narratives")
+received = sorted(root.rglob("*.received.nt")) if root.is_dir() else []
+if not received:
+    print("no approval traces configured yet under test-narratives -- nothing pending")
+else:
+    newest = received[-1]
+    approved = newest.with_name(newest.name.replace(".received.nt", ".approved.nt"))
+    print("received: " + str(newest))
+    if approved.is_file():
+        print("approved: " + str(approved))
+        print(approved.read_text(encoding="utf-8"))
+        print("--- vs received ---")
+    else:
+        print("no .approved.nt yet -- first approval, review then promote")
+    print(newest.read_text(encoding="utf-8"))
+'
+```
+
+## Always
+
+- Run the doctor CLI and read its report before making any change. (the tested tooling already computed the finding -- re-deriving it by hand risks disagreeing with what ships)
+
+## Never
+
+- Never have this skill edit, generate, or delete a file. (narrativetrace-doctor is scoped read-only by design -- generation of the redaction-proof test itself is a separate, later skill)
+- Never claim a finding passed without having run the doctor CLI in this session. (self-reported success overstates reality -- a build claimed green that does not reproduce from clean is not evidence; verify is never 'ask the agent')

narrativetrace-0.2.0/src/narrativetrace/_skills/catalogue.json

@@ -0,0 +1,17 @@
+{
+  "runtime": "python",
+  "skills": [
+    {
+      "name": "narrativetrace-doctor",
+      "description": "Diagnoses a NarrativeTrace Python install and configuration. Use when nothing is being traced, no trace output files appear, DuplicateConfigurationError shows up on startup, a *args method's parameters render as one args: [...] value, or you are not sure NarrativeTrace is wired up correctly. Checks the interpreter and pytest versions, that all eight narrativetrace-* packages agree on one version, NARRATIVETRACE_OUTPUT, that the pytest plugin is registered and not disabled, whether the NarrativeTrace agent skills are installed and current, unrecognized narrativetrace.toml keys, an imported-but-unused not_traced_field/__nt_not_traced__ marker, whether redaction is proven in a test, and stale approval-trace diffs. Read-only -- makes no changes. Say 'check my narrativetrace setup', 'is narrativetrace broken', or 'why isn't anything being traced' to invoke it.",
+      "agents": "agents/narrativetrace-doctor/SKILL.md",
+      "claude": "claude/narrativetrace-doctor/SKILL.md"
+    },
+    {
+      "name": "add-narrative-tracing",
+      "description": "Installs NarrativeTrace into a Python project and gets it to a first trace. Use when NarrativeTrace is not yet installed, a project needs its very first traced call, or traces need to reach a real logger instead of bare print statements. Installs narrativetrace with uv add, wraps an object with trace_object, renders and runs the first trace, then wires the stdlib logging bridge so traces reach your logger. Runs narrativetrace doctor to confirm the install is correctly wired -- narrativetrace-doctor owns diagnosis from there -- and previews the agent-skills install so the next session finds them. Say 'add narrative tracing to my service', 'install narrativetrace', 'get a trace in 60 seconds', 'wrap this object so I can see a trace', or 'send my traces to my logger' to invoke it.",
+      "agents": "agents/add-narrative-tracing/SKILL.md",
+      "claude": "claude/add-narrative-tracing/SKILL.md"
+    }
+  ]
+}

narrativetrace-0.2.0/src/narrativetrace/_skills/claude/add-narrative-tracing/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: add-narrative-tracing
+description: "Installs NarrativeTrace into a Python project and gets it to a first trace. Use when NarrativeTrace is not yet installed, a project needs its very first traced call, or traces need to reach a real logger instead of bare print statements. Installs narrativetrace with uv add, wraps an object with trace_object, renders and runs the first trace, then wires the stdlib logging bridge so traces reach your logger. Runs narrativetrace doctor to confirm the install is correctly wired -- narrativetrace-doctor owns diagnosis from there -- and previews the agent-skills install so the next session finds them. Say 'add narrative tracing to my service', 'install narrativetrace', 'get a trace in 60 seconds', 'wrap this object so I can see a trace', or 'send my traces to my logger' to invoke it."
+when_to_use: "A project does not have NarrativeTrace yet, or has the package installed but has never produced a trace, or traces print to the console but nothing forwards them to a real logger."
+allowed-tools: uv, git
+---
+
+# add-narrative-tracing
+
+## 1. Install with the real toolchain
+
+```bash
+uv sync --all-packages
+```
+
+**verify:** `uv run narrativetrace doctor --json | uv run python -c 'import json, sys
+report = json.load(sys.stdin)
+bad = [f for f in report["findings"] if f["id"].startswith("toolchain.") and f["status"] != "pass"]
+if bad:
+    print(json.dumps(bad))
+sys.exit(1 if bad else 0)
+'`
+
+**failure:** a sibling narrativetrace-* package disagrees on version — an installed distribution outside the lockstep version the other narrativetrace-* packages share. Fix: run the narrativetrace-doctor skill's toolchain.package-versions check, then pin every narrativetrace-* dependency to the same version and `uv sync`
+
+## 2. First trace: wrap, call, render, run
+
+<!-- snippet: examples/sixty_seconds/main.py -->
+```python
+# main.py
+from narrativetrace import ContextVarNarrativeContext, IndentedTextRenderer, TraceId, trace_object
+
+
+class OrderService:
+    def place_order(self, customer_id, product_id, quantity):
+        return f"ORD-{customer_id}-{product_id}-{quantity}"
+
+
+# snippet:begin fixedTraceId
+# A fixed trace id, adopted so this page's embedded output always names the same trace. A real
+# run generates a random one every time (never this -- it is this DEMO's own constant, not the
+# library default) via the same TraceId.adopt_trace_id a servlet-style boundary uses for an
+# inbound trace header.
+DEMO_TRACE_ID = TraceId("a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4")
+
+# snippet:end fixedTraceId
+
+context = ContextVarNarrativeContext()
+context.adopt_trace_id(DEMO_TRACE_ID)
+service = trace_object(OrderService(), context)
+service.place_order("cust-1", "prod-42", 3)
+
+print(IndentedTextRenderer().render(context.capture_trace()))
+```
+<!-- /snippet -->
+
+**verify:** `uv run python main.py`
+
+**failure:** a *args method's parameters render as one args: [...] value — inspect.signature has nothing named to reconstruct per-argument that Python itself does not have. Fix: supply explicit names: @traced("first", "second", ...) above the method
+
+## 3. Send it to your logger
+
+<!-- snippet: examples/sixty_seconds/main_with_logger.py -->
+```python
+# main.py
+import logging  # new: stdlib logging -- the sink this step sends the trace to
+import sys  # new: stdout target for the handler below
+
+from narrativetrace import (
+    ContextVarNarrativeContext,
+    IndentedTextRenderer,
+    NarrativeContextFilter,  # new: injects traceName/runName onto every log record
+    TraceId,
+    export_to_logger,  # new: replays an already-captured trace through your logger, one call
+    trace_object,
+)
+
+
+class OrderService:
+    def place_order(self, customer_id, product_id, quantity):
+        return f"ORD-{customer_id}-{product_id}-{quantity}"
+
+
+# snippet:begin fixedTraceId
+# A fixed trace id, adopted so this page's embedded output always names the same trace. A real
+# run generates a random one every time (never this -- it is this DEMO's own constant, not the
+# library default) via the same TraceId.adopt_trace_id a servlet-style boundary uses for an
+# inbound trace header.
+DEMO_TRACE_ID = TraceId("a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4")
+
+# snippet:end fixedTraceId
+
+# new: a plain stdlib logging setup -- the shape a real app's own logging config already has
+handler = logging.StreamHandler(sys.stdout)
+handler.addFilter(NarrativeContextFilter())  # new: makes traceName/runName available below
+# new: DEBUG so export_to_logger's records pass the handler; the format reads the filter's keys
+logging.basicConfig(
+    level=logging.DEBUG, format="[%(traceName)s] [%(runName)s] %(message)s", handlers=[handler]
+)
+
+context = ContextVarNarrativeContext()
+context.adopt_trace_id(DEMO_TRACE_ID)
+service = trace_object(OrderService(), context)
+service.place_order("cust-1", "prod-42", 3)
+
+trace = context.capture_trace()  # new: capture once, reuse for both the print and the export
+print(IndentedTextRenderer().render(trace))
+
+export_to_logger(trace)  # new: sends the same captured trace through the configured logger
+```
+<!-- /snippet -->
+
+**verify:** `uv run python main_with_logger.py`
+
+## 4. Run the doctor and resolve its findings
+
+```bash
+uv run narrativetrace doctor || true
+```
+
+**verify:** `uv run narrativetrace doctor --json | uv run python -c 'import json, sys
+report = json.load(sys.stdin)
+findings = report.get("findings")
+sys.exit(1 if not isinstance(findings, list) or len(findings) != 12 else 0)
+'`
+
+## 5. Install the skills for next time
+
+```bash
+uv run narrativetrace init --dry-run
+```
+
+**verify:** `uv run python -c 'import pathlib, subprocess, sys
+result = subprocess.run(
+    ["uv", "run", "narrativetrace", "init", "--dry-run"], capture_output=True, text=True
+)
+shown = (
+    "action(s)" in result.stdout
+    and ".agents/skills" in result.stdout
+    and "AGENTS.md" in result.stdout
+)
+untouched = not pathlib.Path(".agents/skills").exists() and not pathlib.Path("AGENTS.md").exists()
+sys.exit(0 if result.returncode == 0 and shown and untouched else 1)
+'`
+
+**failure:** the command exits 1 with no carrier resolved — no narrativetrace-skills distribution is installed and this project's own narrativetrace bundles no reachable fallback. Fix: run `uv add narrativetrace-skills`, or point --from at a local carrier directory or wheel
+
+## Always
+
+- Reinstall clean (`uv sync`) rather than trusting whatever is already in the virtual environment. (a mismatched sibling version or a stale lockfile is the single most common install failure, and it only surfaces on a clean install)
+
+## Never
+
+- Never assume a step worked without running its verify. (self-reported success overstates reality -- a build claimed green that does not reproduce from clean is not evidence)
+- Never skip the final narrativetrace doctor call. (it is the seam that catches anything these four steps did not -- narrativetrace-doctor owns diagnosis from here)
+- Never apply the installer without showing its diff first. (it writes into AGENTS.md and the project's skill directories, and the approval for that is a person reading the diff -- run it with --dry-run, show the output, and let them run it again without the flag)

narrativetrace-0.2.0/src/narrativetrace/_skills/claude/narrativetrace-doctor/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: narrativetrace-doctor
+description: "Diagnoses a NarrativeTrace Python install and configuration. Use when nothing is being traced, no trace output files appear, DuplicateConfigurationError shows up on startup, a *args method's parameters render as one args: [...] value, or you are not sure NarrativeTrace is wired up correctly. Checks the interpreter and pytest versions, that all eight narrativetrace-* packages agree on one version, NARRATIVETRACE_OUTPUT, that the pytest plugin is registered and not disabled, whether the NarrativeTrace agent skills are installed and current, unrecognized narrativetrace.toml keys, an imported-but-unused not_traced_field/__nt_not_traced__ marker, whether redaction is proven in a test, and stale approval-trace diffs. Read-only -- makes no changes. Say 'check my narrativetrace setup', 'is narrativetrace broken', or 'why isn't anything being traced' to invoke it."
+when_to_use: "A project already has NarrativeTrace installed and something about it is not working, or an agent wants a pre-flight check before wiring it into new code."
+allowed-tools: uv, git
+---
+
+# narrativetrace-doctor
+
+## 1. Run the doctor and read its report
+
+```bash
+uv run narrativetrace doctor || true
+```
+
+**verify:** `uv run narrativetrace doctor --json | uv run python -c 'import json, sys
+report = json.load(sys.stdin)
+findings = report.get("findings")
+sys.exit(1 if not isinstance(findings, list) or len(findings) != 12 else 0)
+'`
+
+**failure:** the CLI's JSON output does not parse, or is missing findings — the CLI crashed instead of reporting a finding. Fix: re-run `uv run narrativetrace doctor --json` directly and read the raw output -- a crash here is a doctor bug, never a project finding
+
+## 2. Prove redaction in a test
+
+```bash
+uv run python -c 'print(
+    "Render a call with a deny-listed parameter name (e.g. password or token) in a test and "
+    "assert the output contains [REDACTED], and that a neighboring non-sensitive value is still "
+    "present."
+)
+'
+```
+
+**verify:** `uv run narrativetrace doctor --json | uv run python -c 'import json, sys
+report = json.load(sys.stdin)
+by_id = {f["id"]: f for f in report["findings"]}
+finding = by_id.get("trap.redaction-proof")
+sys.exit(1 if finding is None or finding["status"] not in ("pass", "fail") else 0)
+'`
+
+**failure:** not_traced_field/__nt_not_traced__ is present but never applied — trusting redaction by inspection instead of proving it in a test. Fix: render a call with a deny-listed parameter name and assert the output contains "[REDACTED]"
+
+## 3. Read the rendered trace before asserting
+
+```bash
+uv run python -c 'import pathlib
+root = pathlib.Path("narrative-traces")
+files = sorted(root.rglob("*.md"), key=lambda p: p.stat().st_mtime) if root.is_dir() else []
+if not files:
+    print("no rendered .md file found yet under narrative-traces -- run your tests or app once")
+else:
+    newest = files[-1]
+    print(newest)
+    print(newest.read_text(encoding="utf-8"))
+'
+```
+
+## 4. Approval flow: diff the structural trace, not just values
+
+**Flagged:** unstudied -- eval cell pending
+
+```bash
+uv run python -c 'import pathlib
+root = pathlib.Path("test-narratives")
+received = sorted(root.rglob("*.received.nt")) if root.is_dir() else []
+if not received:
+    print("no approval traces configured yet under test-narratives -- nothing pending")
+else:
+    newest = received[-1]
+    approved = newest.with_name(newest.name.replace(".received.nt", ".approved.nt"))
+    print("received: " + str(newest))
+    if approved.is_file():
+        print("approved: " + str(approved))
+        print(approved.read_text(encoding="utf-8"))
+        print("--- vs received ---")
+    else:
+        print("no .approved.nt yet -- first approval, review then promote")
+    print(newest.read_text(encoding="utf-8"))
+'
+```
+
+## Always
+
+- Run the doctor CLI and read its report before making any change. (the tested tooling already computed the finding -- re-deriving it by hand risks disagreeing with what ships)
+
+## Never
+
+- Never have this skill edit, generate, or delete a file. (narrativetrace-doctor is scoped read-only by design -- generation of the redaction-proof test itself is a separate, later skill)
+- Never claim a finding passed without having run the doctor CLI in this session. (self-reported success overstates reality -- a build claimed green that does not reproduce from clean is not evidence; verify is never 'ask the agent')

narrativetrace-0.2.0/src/narrativetrace/doctor/__init__.py

@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: BUSL-1.1
+# Licensed under the Business Source License 1.1 (see LICENSE); Change Date: four
+# years from publication; Change License: Apache-2.0
+# Copyright (c) 2026 Empower Agile
+"""``narrativetrace doctor``'s one impure half, and the console script every verb goes through.
+
+Every check, the report, both renderings and the whole agent-skills installer live in
+:mod:`narrativetrace_tooling` — the zero-dependency library this distribution's console script
+launches, and which a second entry point can embed without dragging the runtime in with it. What
+stays here is what cannot move:
+
+* :mod:`narrativetrace.doctor.environment` — builds the
+  :class:`~narrativetrace_tooling.doctor.types.DoctorSnapshot` by walking the real project and the
+  installed-distribution metadata. It resolves configuration through
+  :class:`narrativetrace.config.ConfigResolver`, the same resolver the runtime itself uses, so the
+  doctor reads a project exactly as the runtime does rather than guessing at the precedence again.
+* :mod:`narrativetrace.doctor.cli_bin` — the ``narrativetrace`` console script: verb dispatch for
+  ``doctor``, ``init`` and ``uninstall``, process exit codes, stdout and stderr. It sits beside the
+  doctor's reader rather than higher up because ``doctor`` was its first verb and this module path
+  is the one ``[project.scripts]`` names; the launcher itself is about all three.
+
+Not part of the package's public API (:mod:`narrativetrace`'s ``__all__``) — reached only through
+the ``narrativetrace`` console script, the same way ``narrativetrace-approve``
+(:mod:`narrativetrace.cli`) is a console-script-only module.
+"""
+
+from __future__ import annotations