> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stratalint.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Install Strata, point it at a repository, and read your first faults in a few minutes.
This guide gets Strata running against a Python repository, explains the
configuration it needs, and walks through reading its output.
## Prerequisites
* Python 3.12 or newer.
* A Python repository with a `src/`-style package layout.
The PyPI distribution is named `stratalint`; the command it installs is
`strata`. You install `stratalint` once and type `strata` from then on.
## 1. Install
```bash theme={null}
pip install stratalint
```
Install Strata into the same environment as the project you want to check. Because
Strata parses your code with the interpreter it runs under, running it in the
project's environment means it parses the project's syntax by construction.
## 2. Configure
Strata reads a `strata.toml` from your repository, or a `[tool.strata]` table in
`pyproject.toml`. Create a `strata.toml` at the repository root:
```toml theme={null}
roots = ["src/my_package"]
tests = ["tests"]
tooling = ["scripts"]
```
Each key declares a **scope** that receives a different set of rules:
| Key | Scope | What it gets |
| --------- | ------------ | ------------------------------------------------------------------------------------------- |
| `roots` | Product code | The full structural rule set: layers, roles, shape, naming, hygiene, annotations. Required. |
| `tests` | Test suite | Test-convention rules and annotation rules. Defaults to `["tests"]`. |
| `tooling` | Dev tooling | The same structural rules as product roots, at one less nesting level. Optional. |
`roots` is the only required key and must not contain nested or overlapping paths.
Anything outside all three scopes is not scanned.
That is the whole minimal config. By default every Strata rule family is on, so you
do not select anything to get started. When you want to narrow what runs, use
`select` and `ignore`; see [choosing rules](/concepts/configuration#selection) for
how. Full schema in [Configuration](/concepts/configuration).
## 3. Check
Run Strata against the configured repository:
```bash theme={null}
strata check
```
If everything conforms, Strata prints a summary and exits `0`:
```text theme={null}
Found 0 faults
```
When Strata finds a problem, it prints a diagnostic for each fault and exits `1`.
The output points at the exact line, shows the source, and explains the fix:
```text theme={null}
SFA002 function 'run' must define a return type annotation
--> src/my_package/main/run.py:5:0
|
5 | def run(a, b):
| ^
|
= help: Declare the returned value type, using None when the function returns no value.
SFS120 function has 2 positional parameters
--> src/my_package/main/run.py:5:0
|
5 | def run(a, b):
| ^
|
= help: Insert * before optional or secondary parameters so call sites name their meaning.
```
Every diagnostic has two parts: the `message` states the contract that was
violated, and the `= help:` line states the normal correction. The messages are
written to be read at the moment of violation, by a person or an agent, so the fix
is clear without opening the docs.
You can also check specific paths instead of the configured roots by passing them
as arguments:
```bash theme={null}
strata check src/my_package/main
```
## 4. Inspect a rule
Any code in the output can be looked up in full:
```bash theme={null}
strata rule SFS120
```
```text theme={null}
SFS120 keyword-only-arguments
Family: shape
Severity: error
Kind: core
Enabled by default: yes
Source: core
Message: ...
Remediation: ...
```
See [`strata rule`](/cli/rule) for details.
## 5. Choose which rules run
Every family is on by default. To narrow that, use `select` and `ignore` in your
config. They take family prefixes (`SFL`, `SFS`, ...) and individual rule codes
(`SFS120`), the same way you would in a tool like ruff.
```toml theme={null}
# Run only some families:
select = ["SFL", "SFR", "SFS", "SFN"]
# Or run everything except a few rules:
select = ["SF"]
ignore = ["SFX007", "SFA103"]
# Or run only a hand-picked set of rules:
select = ["SFL001", "SFL101", "SFS120"]
```
See [choosing rules](/concepts/configuration#selection) for how selection composes.
Rolling Strata out on an existing codebase rather than a new one? See
[Adopting Strata](/adoption) for a gradual approach.
## 6. See the shape
Where `strata check` enforces structure, [`strata map`](/cli/map) renders it. Point
it at a function to get a deterministic downstream call tree:
```bash theme={null}
strata map run
```
```text theme={null}
run(...) src/my_package/main/run.py:5
├── load(...) src/my_package/main/load.py:8
└── render(...) src/my_package/main/render.py:12
```
`strata map` does not require Strata configuration or rule adoption, so you can use
it on any repository. Locations are repository-relative by default so editors like
VS Code can make them clickable. See [`strata map`](/cli/map) for depth, path, and
import-root options.
## 7. Generate agent guidance
If agents work in your repository, generate skill files from your active rules so
their instructions stay in sync with what CI enforces:
```bash theme={null}
strata skills update
```
This installs a `SKILL.md` for each supported agent. See
[`strata skills`](/cli/skills).
## Next steps
The scopes, roles, and default layout Strata enforces.
Every configuration key, threshold, and contract.
What each family (SFL, SFR, SFS, SFN, SFX, SFT, SFA) checks.
Why Strata is strict by default and how to deviate deliberately.