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, Reviewed product KPI evidence, Rust adoption-to-diagnosis proof, CircleCI proof-command discovery, Azure DevOps proof-command discovery, Artifact reference, Investigation operator guide | Read-only external-repo evidence, complete ecosystem and provider proofs, reviewed denominators, learning observations, detector upgrades, and roadmap/radar control panels. |
| Product direction | Product roadmap, Current product delta, Platform capability matrix, Reviewed KPI evidence contract, Remediation research contract, Remediation research guide, Formatter candidate benchmark, Formatter verifier and trajectory proof, Formatter policy proposal eligibility, Formatter policy proposal observation | Use the roadmap for execution order, the delta for released-versus-main truth, the matrix for implemented capabilities and gaps, the KPI contract for reviewed product measurements, the remediation contract for review-first candidate evidence, the benchmark guide for disposable formatter evaluation, and the verifier guide for read-only evidence composition. Keep these secondary to the operator path. |
| Maintenance / autopilot | Artifact reference, Operations handbook, Automation bots, Remediation research guide, Formatter candidate benchmark, Formatter verifier and trajectory proof, Formatter policy proposal eligibility, Formatter policy proposal observation | Treat plans, candidates, safe-fix outputs, benchmark outputs, verifier outputs, trajectories, memory profiles, and remediation-research reports 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 and this map when the contract controls roadmap or operator decisions; do not duplicate 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. |
| Rust end-to-end proof | Rust adoption-to-diagnosis proof, Doctor report contract | Carry explicit Rust repository evidence and saved Cargo failures into the shared review-first diagnosis contract. |
| CircleCI provider proof | CircleCI proof-command discovery, Adopt in your repository | Extract literal repository-owned run evidence while keeping orbs, parameters, dynamic configuration, and execution review-first. |
| Azure DevOps provider proof | Azure DevOps proof-command discovery, Adopt in your repository | Extract literal root pipeline scripts while keeping templates, expressions, variables, tasks, matrices, deployments, service connections, and execution review-first. |
| Evidence and learning loop | Reviewed product KPI evidence, Investigation operator guide, Adaptive Diagnosis Intelligence | Convert reviewed observations into explicit denominators, then convert repeated gaps into detector, report, and memory upgrades. |
| Roadmap control panels | Product roadmap, Current product delta, Platform capability matrix, Reviewed KPI evidence contract, Remediation research contract, Remediation research guide, Formatter candidate benchmark, Formatter verifier and trajectory proof, Formatter policy proposal eligibility, Formatter policy proposal observation, Curated advanced docs material map, Artifact reference | Use maintained product-control contracts, benchmark evidence, and verifier/trajectory evidence to choose focused slices; do not let generated trackers, candidate reports, or unreviewed metrics replace product direction. |
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: