Docs map and organization¶
Use this map when the docs/ tree feels large. It separates the primary operator path from generated/sample artifacts, advanced programs, and historical material.
Read in this order¶
| Step | Use this page | Why |
|---|---|---|
| 1 | Start here homepage | Product homepage/router and canonical first path. |
| 2 | Start Here in 5 Minutes | Quick first run without browsing the whole tree. |
| 3 | Operator essentials | Day-to-day runbook for first proof, failed CI triage, autopilot review, and guarded remediation review. |
| 4 | Artifact reference and generated sample map | Runtime artifacts, workflow uploads, generated/sample labels, and artifact-to-action guidance. |
| 5 | Investigation operator guide | Diagnostic-only failure investigation with sdetkit investigate. |
| 6 | Remediation cookbook | Human remediation playbooks after evidence identifies a failure class. |
Information architecture¶
| Area | Primary docs | Notes |
|---|---|---|
| Getting started | Install, Quickstart, Blank repo to value, Ready to use | Keep these copy-pasteable and starter-oriented. |
| Operator guide | Operator essentials, Local diagnostic queue operator guide, Operator onboarding, Recommended CI flow | Daily operator work belongs here, not in the README. |
| Investigation / diagnosis | Investigation operator guide, Adaptive Diagnosis Intelligence, First failure triage | Diagnostic/report-only unless a guarded lane explicitly authorizes mutation. |
| Real-world adoption and learning | Adopt in your repository, Artifact reference, Investigation operator guide | Read-only external-repo evidence, learning observations, detector upgrades, and roadmap/radar control panels. |
| Maintenance / autopilot | Artifact reference, Operations handbook, Automation bots | Treat plans, candidates, and safe-fix outputs as evidence until reviewed policy approves the next step. |
| Quality gates | Premium quality gate, Security gate, Determinism checklist, Determinism contract | Gate docs explain proof and policy, not broad default auto-fix. |
| Artifact reference | Artifact reference, CI artifact walkthrough, Evidence showcase | Runtime artifacts live under build/ and .sdetkit/; committed examples live under docs/artifacts/. |
| Contributor / developer docs | Repo tour, Contributing, Release process, Test bootstrap, Project structure | Keep implementation and contribution material secondary to the operator path. |
| Generated/sample artifacts | Artifact reference, Live-adoption product proof | Historical packs are preserved for traceability and are not the current runbook. |
| Historical archive | Archive overview, Transition-era material map | Non-primary; use only after the canonical path is working. |
Directory guide¶
| Directory | Contents | Tidy rule |
|---|---|---|
docs/ |
Primary human docs and reference pages. | New primary guides must be linked from Start here homepage or this map. |
docs/artifacts/ |
Committed generated/sample artifacts, proof packs, and historical completion material. | Label as generated/sample; do not treat as current runtime evidence. |
docs/archive/ |
Historical and transition-era docs. | Keep non-primary material here when it is no longer part of the operator path. |
docs/business_execution/ |
Business execution and GTM planning docs. | Keep business/program material out of first-run operator docs. |
docs/contracts/ |
Formal contracts and schema-oriented references. | Link from the relevant feature doc instead of duplicating contract text. |
docs/integrations/ |
Integration packs and external workflow examples. | Keep platform-specific setup here. |
docs/kits/ |
Kit-level packaging and capability docs. | Use after the core operator path is trusted. |
docs/project/ |
Project-level architecture, workflow, release, quality, and enterprise docs. | Keep root copies as compatibility pointers only when checks or external links require them. |
docs/roadmap/ |
Roadmap artifacts and reports. | Keep roadmap/reporting secondary to current operator guidance. |
Navigation rules for future cleanup¶
Real-world learning lanes¶
Use these pages when SDETKit is being evaluated as a repository doctor rather than only a local release gate:
| Lane | Primary pages | Operator rule |
|---|---|---|
| Adoption surface | Adopt in your repository, Artifact reference | Detect repo shape and proof surfaces before recommending commands. |
| Evidence and learning loop | Investigation operator guide, Adaptive Diagnosis Intelligence | Convert repeated gaps into detector/report/memory upgrades. |
| Roadmap control panels | Docs map and organization, Curated advanced docs material map, Artifact reference | Use radar/report outputs to choose focused PRs; do not replace the roadmap. |
External repositories remain learning targets, not patch targets. Default posture is no install, no target tests, no mutation, no target PRs/issues, and no endorsement claim.
- Keep the README as a concise front door; move command matrices to focused docs.
- Keep Operator essentials as the day-to-day runbook.
- Keep Artifact reference as the source of truth for runtime and uploaded artifact paths.
- Do not move historical/generated artifact packs unless a separate migration map and link update are included.
- Preserve the safety story everywhere: diagnostic/report-only by default; mutation only through explicit guarded policy and PR-only controls.
Diagnostic intelligence¶
Evidence circuit review bundle¶
The completed evidence circuit documentation bundle consists of: