> ## Documentation Index
> Fetch the complete documentation index at: https://tashfiq.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Charter to an Existing Repo

> Baseline your first scan, fix what is safe, and commit Charter in under 10 minutes.

Use this path when you already have a working repository and want to add Charter without reshaping the repo all at once. The full adoption loop takes under 10 minutes on most repos.

<Steps>
  <Step title="Scaffold missing baseline files">
    Run `charter init` to create any missing baseline files — without touching what already exists:

    ```bash theme={null}
    charter init --path .
    ```

    What gets created (only if the file is not already present):

    | File                    | Purpose                                           |
    | ----------------------- | ------------------------------------------------- |
    | `AGENTS.md`             | Agent context and repo instructions               |
    | `charter.yaml`          | Policy configuration                              |
    | `.gitignore`            | Common agent artifact patterns                    |
    | `ARCHITECTURE.md`       | High-level module layout                          |
    | `.env.example`          | Environment variable documentation                |
    | `.claude/settings.json` | Claude tool permissions (when Claude is detected) |

    Want to preview before writing anything?

    ```bash theme={null}
    charter init --path . --dry-run
    ```

    <Tip>
      `init` is create-missing-only. It will never overwrite an existing `AGENTS.md` or `charter.yaml`. Run it freely even on repos that are partially set up.
    </Tip>
  </Step>

  <Step title="Run the baseline scan">
    Once the missing baseline files exist, run the first scan:

    ```bash theme={null}
    charter doctor
    ```

    <Frame caption="charter doctor — first scan on an existing repo with findings">
      <img src="https://mintcdn.com/tashfiq/JQQfhNhXhSPPRZxR/images/screenshots/adopt-first-scan.webp?fit=max&auto=format&n=JQQfhNhXhSPPRZxR&q=85&s=20ccfdbfa4a846a4ed82aab4da00dcac" alt="charter doctor first scan output" width="1728" height="2442" data-path="images/screenshots/adopt-first-scan.webp" />
    </Frame>

    The output shows:

    * your current score
    * active findings grouped by rule
    * which findings are blockers (Hard caps: secret findings cap at 49, blocker findings cap at 59)
    * whether the repo already meets the standard gate

    <Info>
      Don't be alarmed by a low first score. Most repos score 40–60 before any fixes. The output tells you exactly what to address — treat the first scan as a triage pass, not a verdict on the repo.
    </Info>

    If you want a machine-readable baseline for later comparison:

    ```bash theme={null}
    mkdir -p .charter
    charter doctor --format json --out .charter/charter-baseline.json
    ```
  </Step>

  <Step title="Fix what Charter can fix safely">
    Review the auto-fix diffs before applying anything:

    <CodeGroup>
      ```bash Dry run first theme={null}
      charter fix --dry-run
      ```

      ```bash Apply fixes theme={null}
      charter fix
      ```

      ```bash Target a single rule theme={null}
      charter fix --rule AE-CTX-004
      ```
    </CodeGroup>

    Charter's safe fixers cover exactly four rules:

    <AccordionGroup>
      <Accordion title="AE-CTX-001 — Creates AGENTS.md">
        Generates an `AGENTS.md` template populated with your detected language, toolchain, and CI platform. Review the template — the generated content is a starting point, not a finished doc.
      </Accordion>

      <Accordion title="AE-CTX-004 — Appends .gitignore entries">
        Adds agent artifact patterns (`.charter/`, `*.charter-session`, `.claude/local/`, `.cursor/cache/`) to your `.gitignore`. Review before committing to make sure no existing entries conflict.
      </Accordion>

      <Accordion title="AE-CI-002 — Creates the Charter GitHub Actions workflow">
        Creates `.github/workflows/charter.yaml`. Check the threshold value and that the SHA pins match what you want before committing.
      </Accordion>

      <Accordion title="AE-MCP-001 — Bumps an unpinned MCP package version">
        Updates floating `@latest` or semver-range MCP server references to an exact pinned version from Charter's catalog. Verify the resolved version is the one you want.
      </Accordion>
    </AccordionGroup>

    <Warning>
      Always run `charter fix --dry-run` first. Read each unified diff before applying. The diff is the contract.
    </Warning>

    Charter backs up any existing file it modifies to `.charter/backups/<timestamp>/` before writing.
  </Step>

  <Step title="Review remaining findings">
    For each finding Charter cannot auto-fix, resolve it manually:

    <CardGroup cols={2}>
      <Card title="AE-SEC-001 / AE-SEC-002" icon="key">
        Remove the secret, rotate the credential, and replace it with an environment variable reference. Never suppress a live secret finding.
      </Card>

      <Card title="AE-TEST-001" icon="flask">
        Add a test suite. Charter looks for evidence of a test runner in your toolchain config and CI — a test file or `package.json` script is enough to pass.
      </Card>

      <Card title="AE-ENV-001" icon="settings">
        Add a toolchain file (`mise.toml`, `.tool-versions`, or a language-native equivalent) so the repo's runtime versions are reproducible.
      </Card>

      <Card title="AE-MCP-003" icon="lock">
        Add an auth header to each remote MCP server entry. Use an env var reference — never a literal credential value.
      </Card>
    </CardGroup>
  </Step>

  <Step title="Suppress accepted risks">
    If a finding is a confirmed false positive or an intentionally accepted exception, record it explicitly:

    ```bash theme={null}
    charter suppress AE-CI-002 \
      --reason "CI integration planned for Q3" \
      --expires 90d
    ```

    This writes a governed entry to `.charter-suppress.yml` with the rule ID, your reason, and an expiry date that re-surfaces later.

    <Warning>
      Suppress only when the repo state is intentionally accepted. If the underlying problem is real, fix it — don't suppress it. Suppression is an audit trail, not a mute button.
    </Warning>

    Permanent suppressions require `--approver`. Without it, [`AE-SUPPRESS-002`](/rules/AE-SUPPRESS-002) fires as a High finding on every scan.
  </Step>

  <Step title="Commit">
    Stage the files Charter created or modified:

    ```bash theme={null}
    git add AGENTS.md charter.yaml .gitignore
    git commit -m "chore: add Charter agent-readiness baseline"
    ```

    Then open a pull request to add CI. Use the workflow file Charter generated at `.github/workflows/charter.yaml`, or follow the [GitHub Actions guide](/docs/ci/github-action).
  </Step>
</Steps>

<Note>
  **What score to target:** 80 is the standard threshold. A first-pass fix run typically moves a blank repo from 40–60 up to 75–90 within 30 minutes. You do not need to reach a perfect score on day one — you need a repo state that is explainable, reviewable, and repeatable.
</Note>

## Quick reference loop

```bash theme={null}
charter init --path .
charter doctor
charter fix --dry-run
charter fix
charter doctor
```

## Next steps

<CardGroup cols={2}>
  <Card title="Use charter fix Safely" icon="shield-check" href="/docs/how-to/use-charter-fix-safely">
    Review and apply auto-fixes without surprises.
  </Card>

  <Card title="Run Charter in GitHub Actions" icon="git-branch" href="/docs/how-to/run-in-github-actions">
    Gate every pull request on the agent-readiness score.
  </Card>

  <Card title="Use Charter in a Pre-Commit Hook" icon="git-commit" href="/docs/how-to/pre-commit-hook">
    Catch regressions before they reach CI.
  </Card>

  <Card title="Agent Readiness Model" icon="compass" href="/docs/concepts/agent-readiness-model">
    What the score measures and why it is a repo property.
  </Card>
</CardGroup>