From ec85040702953b7db61a3d19ff074978229b111c Mon Sep 17 00:00:00 2001 From: stacknil Date: Tue, 9 Jun 2026 14:35:04 +0800 Subject: [PATCH] docs(review): add docs index --- README.md | 1 + docs/README.md | 29 +++++++++++++++++++++++++++++ tests/test_reviewer_docs.py | 28 ++++++++++++++++++++++++++++ 3 files changed, 58 insertions(+) create mode 100644 docs/README.md diff --git a/README.md b/README.md index 3205416..e727ed9 100644 --- a/README.md +++ b/README.md @@ -142,6 +142,7 @@ Cooldown behavior: - [`demos/rule-evaluation-and-dedup-demo/README.md`](demos/rule-evaluation-and-dedup-demo/README.md) explains the third demo and links its committed before/after dedup artifacts - [`demos/config-change-investigation-demo/README.md`](demos/config-change-investigation-demo/README.md) explains the config-change investigation demo and its committed artifacts +- [`docs/README.md`](docs/README.md) indexes current reviewer docs, supporting design notes, and historical release evidence - [`docs/reviewer-pack.md`](docs/reviewer-pack.md) is the top-level no-guessing reviewer pack and artifact naming contract - [`docs/reviewer-brief.md`](docs/reviewer-brief.md) gives the short problem, value, evidence, and boundary summary - [`docs/reviewer-path.md`](docs/reviewer-path.md) maps common review questions to the right demo and artifacts diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..8b5c969 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,29 @@ +# telemetry-lab docs + +This directory separates the current reviewer route from supporting design notes and historical release evidence. The repo is a local, file-based detection workflow lab, not a SIEM, dashboard, or production monitoring platform. + +## Current reviewer route + +- [`reviewer-pack.md`](reviewer-pack.md): top-level reviewer pack, demo matrix, artifact naming contract, and v1 readiness gate +- [`reviewer-path.md`](reviewer-path.md): choose a demo by review question +- [`reviewer-brief.md`](reviewer-brief.md): short problem, value, evidence, and boundary summary +- [`architecture.md`](architecture.md): local file-based workflow diagram +- [`roadmap.md`](roadmap.md): v0.7 / v1.0 consolidation direction + +## Supporting docs + +- [`sample-output.md`](sample-output.md): committed output counts and sample artifacts +- [`design-notes.md`](design-notes.md): original telemetry-window design boundaries +- [`ai-assisted-detection-design.md`](ai-assisted-detection-design.md): bounded AI-assisted detection design +- [`ai-assisted-detection-examples.md`](ai-assisted-detection-examples.md): example AI-assisted detection outputs and guardrail behavior +- [`ai-assisted-detection-reviewer-pack.md`](ai-assisted-detection-reviewer-pack.md): reviewer pack for the AI-assisted demo +- [`config-change-investigation-demo-design.md`](config-change-investigation-demo-design.md): config-change investigation design notes +- [`config-change-investigation-reviewer-pack.md`](config-change-investigation-reviewer-pack.md): reviewer pack for the config-change investigation demo + +## Historical release evidence + +These files are retained as release evidence snapshots. Use the current reviewer route above for the maintained review path. + +- [`release-v0.4.0.md`](release-v0.4.0.md) +- [`reviewer-pack-v0.4.0/MANIFEST.md`](reviewer-pack-v0.4.0/MANIFEST.md) +- [`reviewer-pack-v0.6.0/MANIFEST.md`](reviewer-pack-v0.6.0/MANIFEST.md) diff --git a/tests/test_reviewer_docs.py b/tests/test_reviewer_docs.py index e6a7944..088e5ad 100644 --- a/tests/test_reviewer_docs.py +++ b/tests/test_reviewer_docs.py @@ -111,6 +111,7 @@ def test_readme_links_reviewer_path_and_uses_lab_framing() -> None: assert "A local, file-based detection workflow lab" in readme assert "local, reviewer-oriented detection workflow lab" in readme assert "not a SIEM, dashboard, or monitoring platform" in readme + assert "[`docs/README.md`](docs/README.md)" in readme assert "[`docs/reviewer-pack.md`](docs/reviewer-pack.md)" in readme assert "[`docs/reviewer-brief.md`](docs/reviewer-brief.md)" in readme assert "[`docs/reviewer-path.md`](docs/reviewer-path.md)" in readme @@ -119,6 +120,33 @@ def test_readme_links_reviewer_path_and_uses_lab_framing() -> None: assert "mvp only" not in normalized +def test_docs_index_separates_current_route_from_history() -> None: + docs_index = _read_repo_file("docs/README.md") + normalized = docs_index.lower() + + assert "Current reviewer route" in docs_index + assert "Supporting docs" in docs_index + assert "Historical release evidence" in docs_index + assert "Use the current reviewer route above" in docs_index + assert "not a siem, dashboard, or production monitoring platform" in normalized + + for current_doc in [ + "reviewer-pack.md", + "reviewer-path.md", + "reviewer-brief.md", + "architecture.md", + "roadmap.md", + ]: + assert f"({current_doc})" in docs_index + + for historical_doc in [ + "release-v0.4.0.md", + "reviewer-pack-v0.4.0/MANIFEST.md", + "reviewer-pack-v0.6.0/MANIFEST.md", + ]: + assert f"({historical_doc})" in docs_index + + def test_package_metadata_uses_detection_lab_framing() -> None: pyproject = _read_pyproject() description = str(pyproject["project"]["description"])