Know what MARS writes, preserves, reads, and removes.

Ownership Model

MARS separates durable repo truth from local runtime machinery. If a file describes product intent, agent doctrine, tickets, evidence, release state, or target-specific policy, it belongs in git. If it is a queue, local model, process log, cache, secret value, or machine-specific setting, it belongs outside git or in an ignored local file.

Target Repo Files

mars init, mars register, and mars scan ensure a target harness exists. mars start and mars run do so only in acknowledged-host mode; default observer rejects a missing target before writes apart from the explicit no-init dry-run preview. The first scaffold is committed as a generated harness baseline when possible.

.
|-- AGENTS.md
|-- VERSION
|-- CHANGELOG.md
|-- .gitignore
|-- .harness/
|-- docs/
    |-- goals/
    |-- exec-plans/
    |-- features/
    |-- tickets/
    |-- design-docs/
    |-- references/
    |-- reports/
    +-- QUALITY_SCORE.md

Harness Directory

.harness/ is executable agent configuration. It is repo-owned, reviewable, and intentionally editable. Existing user content is preserved by ordinary init/upgrade paths; --force refreshes missing scaffold and rewrites only selected generated defaults while preserving user-owned content such as custom prompts and tickets.

Operating Docs

MARS uses repo docs as live operating state. These artifacts are not background notes. Agents read and update them as part of delivery, review, validation, and release.

Local State

The user machine state under ~/.mars/ is not part of a target repo. It stores configuration, downloaded models, managed binaries, SQLite state, traces, logs, and auth setup needed for local operation.

mars doctor --json
mars doctor --repo /path/to/repo --json

Databases

SQLite state is isolated by default for repo-scoped operation. Use explicit --db paths only when you understand the lifecycle and cleanup implications.

Logs And Traces

run, start, and serve write durable command logs under ~/.mars/traces/logs/ unless --log-file is supplied. Role traces and summaries are local runtime evidence. Copy only the relevant finding into repo reports or tickets when the evidence needs to become durable.

mars start --repo /path/to/repo
mars run engineer --repo /path/to/repo

mars start --repo /path/to/repo \
  --log-file ~/.mars/traces/logs/my-project-start.log

Do not put logs inside the target repo. MARS validates lifecycle log paths so process output does not become accidental source churn.

Models And Secrets

Model files, provider keys, and local routing choices have different persistence rules. Keep large model artifacts and secret values out of git. Commit only reusable routing policy and empty example keys. Use the Authentication And Credentials Reference for command-by-command credential setup and verification.

mars models override --repo /path/to/repo --role engineer --provider openai --model gpt-4.1 --api-key-env OPENAI_API_KEY
export OPENAI_API_KEY=...
mars models credentials write-local-env --repo /path/to/repo --api-key-env OPENAI_API_KEY --yes

Release Assets

Release notes are repo-owned. Binary release assets are generated output. MARS source uses AD-315's no-publish conventional Go/Syft rehearsal; target repositories choose and document their own producer and artifact contract.

mars release notes --repo . --bump auto

Run the no-publish production and verification steps authorized by AD-315. T-080 activates .github/workflows/release.yml only for an exact repository tag after the approved public gates. That is the MARS source workflow, not generated target doctrine and not publication authority. The standalone verifier and audit are retired; signed consumer and remote-convergence proof remain F-018 gates.

Lifecycle Behavior

Different commands touch different surfaces. This table is the user-level map for expected filesystem changes.

Eject And Cleanup

mars eject is the repo-level kill switch. It previews first. Destructive cleanup requires --apply and a --confirm value equal to the target repo directory name. It removes the deployed MARS surface and associated DB artifacts without rewriting git history or deleting unrelated app files.

mars eject --repo /path/to/repo
mars eject --repo /path/to/repo --apply --confirm repo
mars eject --repo /path/to/repo --apply --confirm repo --keep-db

Recipes

mars eject --repo /path/to/repo

mars doctor --repo /path/to/repo --json
git -C /path/to/repo status --short --branch

ls ~/.mars/traces/logs
mars run engineer --repo /path/to/repo --log-file ~/.mars/traces/logs/engineer.log

mars models override --repo /path/to/repo \
  --tier coding \
  --provider openai \
  --model gpt-4.1 \
  --api-key-env OPENAI_API_KEY
export OPENAI_API_KEY=...
mars models credentials write-local-env --repo /path/to/repo --api-key-env OPENAI_API_KEY --yes

Troubleshooting