MARS Documentation Map

Start And Safe Trial

Use these when evaluating MARS for the first time or checking what can write files.

Path	Purpose	Headline	Use when	Doc type	Canonical status	Used by agents?
`docs/index.html`	Front door and routing.	Inspect, govern, and improve MARS.	Getting the product shape and next evidence route.	Public guide	Summary	No
`docs/quickstart.html`	First successful run.	Install MARS and run one target.	Running the first safe local lifecycle.	Public guide	Reference	No
`docs/install-setup-reference.html`	Install, setup, local inference, and recovery.	Prepare the local runtime.	Preparing or repairing local runtime setup.	Public reference	Reference	No
`docs/shell-integration-reference.html`	PATH setup and shell repair.	Make the command available.	Fixing command lookup or shell integration.	Public reference	Reference	No
`docs/auth-credentials-reference.html`	Credential boundaries and token indirection.	Keep secrets out of repo docs.	Checking secrets, tokens, and authentication boundaries.	Public reference	Reference	No
`docs/adoption-guide.html`	Evidence-based evaluation guide.	Adopt MARS without losing control.	Trying safely, reviewing controls, piloting, and deciding rollout.	Public guide	Summary	No

Daily Operation

Use these after MARS is installed and a target repo is ready.

Path	Purpose	Headline	Use when	Doc type	Canonical status	Used by agents?
`docs/workflows.html`	Task-oriented flows.	Run MARS from install to daily operations.	Choosing the right command flow for a job.	Public guide	Reference	No
`docs/target-lifecycle-reference.html`	Init, upgrade, scan, start, serve, eject.	Manage target harness lifecycle.	Managing a target repo from init to removal.	Public reference	Reference	No
`docs/operations-guide.html`	Run modes and controls.	Operate the local MARS runtime.	Starting, pausing, stopping, and recovering the runtime.	Public guide	Reference	No
`docs/dashboard-api-reference.html`	Dashboard pages, controls, and APIs.	Use local dashboard controls.	Inspecting or integrating dashboard controls.	Public reference	Reference	No
`docs/observability-guide.html`	Logs, traces, metrics, evidence, and recovery.	Understand what happened.	Reading logs, traces, metrics, and run evidence.	Public guide	Reference	No
`docs/troubleshooting-guide.html`	Symptom-driven recovery.	Fix the common failure modes.	Diagnosing and recovering from known problems.	Public guide	Reference	No

Security, Governance, And Ownership

Use these when checking data boundaries, control, evidence, and recovery before increasing autonomy.

Path	Purpose	Headline	Use when	Doc type	Canonical status	Used by agents?
`docs/security-governance-guide.html`	Security, ownership, guardrails, and evidence route.	Govern MARS before trusting autonomy.	Checking data, credentials, guardrails, trust, evidence, and recovery.	Public guide	Summary	No
`docs/safety-quality-guide.html`	Trust levels, guardrails, quality, and recovery.	Bound autonomy and inspect quality.	Checking trust, quality, telemetry, and recovery behavior.	Public guide	Reference	No
`docs/guardrails-reference.html`	Guardrail schema, severity, matching, hooks, recovery.	Define repo-owned policy.	Writing or reviewing repo-owned policy.	Public reference	Reference	Sometimes
`docs/files-state-reference.html`	What files and local state MARS writes and removes.	Know what MARS owns.	Checking file ownership, local state, and eject cleanup.	Public reference	Reference	No
`docs/configuration-reference.html`	Local and target configuration.	Configure without leaking secrets.	Changing local or target configuration safely.	Public reference	Reference	Sometimes
`docs/documentation-sync-guide.html`	No-stale-docs workflow.	Keep public and harness docs aligned.	Keeping human docs and harness docs in sync.	Public guide	Reference	Yes

Agent Team And Delivery Model

Use these to understand how ideas become governed work.

Path	Purpose	Headline	Use when	Doc type	Canonical status	Used by agents?
`docs/planning-delivery-guide.html`	Goal, plan, BDD, ticket, evidence, release chain.	From idea to shipped change.	Understanding how intent becomes shipped work.	Public guide	Reference	Yes
`docs/roles-guide.html`	Roles, domains, modes, and handoffs.	Understand the AI product team.	Inspecting role responsibilities and handoffs.	Public guide	Reference	Yes
`docs/harness-guide.html`	Target harness structure and customization.	Work with the deployed harness.	Reading or adapting a generated harness.	Public guide	Reference	Yes
`docs/checks-evidence-guide.html`	Local check recording and evidence.	Record proof, not vibes.	Recording and reviewing local check evidence.	Public guide	Reference	Sometimes
`docs/release-update-guide.html`	Semantic release notes, assets, updates.	Ship and update deliberately.	Preparing release notes, assets, and updates.	Public guide	Reference	Yes

Extension And Integration

Use these when connecting MARS to tools, models, code intelligence, and optional board flows.

Path	Purpose	Headline	Use when	Doc type	Canonical status	Used by agents?
`docs/cli-reference.html`	Full command surface.	Know the exact command.	Looking up exact command syntax.	Public reference	Reference	No
`docs/tools-mcp-guide.html`	Universal tool surface and MCP bridge.	Expose tools with trust levels.	Exposing tools through trust-aware MCP flows.	Public guide	Reference	Yes
`docs/models-guide.html`	Local inference, optional providers, evaluation, overrides.	Choose models deliberately.	Choosing local models or optional provider routes.	Public guide	Reference	Sometimes
`docs/code-intel-reference.html`	Code graph context, tools, metrics, validation boundaries.	Use local code intelligence as evidence.	Using code graph context and code-intel tools.	Public reference	Reference	Yes
`docs/integrations-validation-guide.html`	Optional integrations and validation matrices.	Validate the connected surfaces.	Connecting optional tools, providers, and validation suites.	Public guide	Reference	Sometimes
`docs/harness-ecosystem/`	Interactive adoption explainer.	Understand the ecosystem story.	Explaining the system model and value case.	Public guide	Summary	No

Canonical System Records

These documents are source-of-truth records for the foundation harness and generated target doctrine.

Path	Purpose	Headline	Use when	Doc type	Canonical status	Used by agents?
`AGENTS.md`	First-read agent guide and operating rules.	How agents work in MARS.	Inspecting the top-level operating rules.	Canonical harness doc	Source of truth	Yes
`README.md`	Repository overview and user entry points.	What MARS is.	Starting from the repository overview.	Repository guide	Reference	Sometimes
`ARCHITECTURE.md`	System architecture overview.	How the runtime is shaped.	Reviewing runtime architecture.	Architecture reference	Reference	Sometimes
`docs/product-specs/`	Product promises and surfaces.	What MARS promises.	Checking product promises and surface area.	Product spec	Source of truth	Yes
`docs/goals/active.md`	Active product and operating goals.	What the system is trying to achieve.	Checking the active goals.	Canonical system record	Source of truth	Yes
`docs/exec-plans/active/current-operating-plan.md`	Current scheduled plan.	What is being worked now.	Checking the current scheduled plan.	Canonical system record	Source of truth	Yes
`docs/features/`	BDD feature contracts and business behavior.	What done means.	Checking feature completeness and business behavior.	BDD contract	Source of truth	Yes
`docs/tickets/`	Ticket lifecycle and work state.	What work exists and what evidence it needs.	Checking ticket state and evidence needs.	Canonical system record	Source of truth	Yes
`docs/design-docs/`	Architecture and operating decisions.	Why the system works this way.	Reading architecture and operating decisions.	Design decision	Source of truth	Yes
`docs/roles/ROLES.md`	Role registry.	Who the agent team is.	Checking the registered role model.	Canonical harness doc	Source of truth	Yes

Validation And Evidence

Use these when proving a claim or replaying a validation path.

Path	Purpose	Headline	Use when	Doc type	Canonical status	Used by agents?
`docs/validation/README.md`	Validation matrix and report rules.	How evidence is recorded.	Recording or replaying validation evidence.	Validation evidence	Source of truth	Yes
`docs/validation/release-blockers.md`	Release blocker ledger.	What blocks release confidence.	Checking known release blockers.	Validation evidence	Source of truth	Yes
`docs/QUALITY_SCORE.md`	Repo-visible quality and role-health score.	How healthy the system looks.	Inspecting visible quality and role-health signals.	Quality evidence	Source of truth	Yes
`CHANGELOG.md`	Versioned user impact and release notes.	What shipped and why.	Checking shipped impact and version history.	Release evidence	Source of truth	Yes
`VERSION`	Current semantic version.	What version this checkout is.	Checking the current semantic version.	Release evidence	Source of truth	Sometimes

Generated And Reference Material

Use these for generated maps, runbooks, research, bundle contracts, and lower-level references.

Path	Purpose	Headline	Use when	Doc type	Canonical status	Used by agents?
`docs/generated/README.md`	Generated reference catalog.	What generated docs exist.	Finding generated reference material.	Generated reference	Reference	Sometimes
`docs/runbooks/README.md`	Operational procedures.	How to run repeatable operations.	Following repeatable operational procedures.	Runbook	Source of truth	Yes when routed
`docs/references/README.md`	Research and external references.	What informed decisions.	Checking research and external inputs.	Reference	Reference	Sometimes
`docs/references/mdn-technical-writing.md`	Technical writing principles.	Write public docs people can use.	Reviewing public documentation writing standards.	Reference	Reference	Sometimes
`docs/bundle-reference.html`	Bundle and manifest contract.	Know the harness bundle shape.	Checking the generated harness bundle contract.	Public reference	Reference	Sometimes
`docs/bundle-reference.md`	Markdown companion for bundle contract.	Manifest detail for maintainers.	Reading manifest detail in Markdown form.	Reference	Reference	Sometimes
`docs/guardrails-guide.md`	Markdown companion for guardrails.	Guardrail usage context.	Reading guardrail usage context in Markdown form.	Reference	Reference	Sometimes

Find the canonical MARS document.