Metadata-Version: 2.4
Name: reporails-cli
Version: 0.5.3
Summary: AI instruction diagnostics for coding agents
Project-URL: Homepage, https://reporails.com
Project-URL: Documentation, https://reporails.com/rules
Project-URL: Repository, https://github.com/reporails/cli
Project-URL: Issues, https://github.com/reporails/cli/issues
Author: Reporails Team
License-Expression: BUSL-1.1
License-File: LICENSE
Keywords: ai-instructions,claude,codex,copilot,cursor,diagnostics,gemini,mcp,validation
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27.0
Requires-Dist: markdown-it-py>=3.0.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: numpy<3,>=1.26
Requires-Dist: onnxruntime<2,>=1.18
Requires-Dist: packaging>=23.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: scikit-learn>=1.4.0
Requires-Dist: spacy<4,>=3.8.11
Requires-Dist: tokenizers<1,>=0.19
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: poethepoet>=0.25.0; extra == 'dev'
Requires-Dist: pylint>=3.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Reporails CLI

AI Instruction Diagnostics for coding agents. Validates the entire agentic instruction system against 97 rules.

### Beta phase — Moving fast, feedback welcome.

## Quick Start

```bash
npx @reporails/cli check
# or
uvx --from reporails-cli ails check
```

## Install

```bash
npx @reporails/cli install
# or
uvx --from reporails-cli ails install
```

This installs `ails` to your PATH and configures the MCP server for detected agents. From then on:

```bash
ails check
ails update               # Upgrade to latest version
```

```
Reporails — Diagnostics — Pro (beta)

  ┌─ Main (1)
  │ CLAUDE.md
  │   ⚠       Missing directory layout — show the project …  CORE:C:0035
  │   ⚠ L9    7 of 7 instruction(s) lack effective reinfor…  CORE:C:0053
  │     ... and 16 more
  │     1 misordered · 1 orphan · 1 ambiguous
  │
  └─ 21 findings

  ── Summary ────────────────────────────────────────────────────────

  Score: 7.9 / 10  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░  (1.3s)
  Agent: Claude

  Scope:
    capabilities: 2 main
    instructions: 4 directive / 7 prose (50%)
                  3 constraint

  21 findings · 4 warnings · 1 info
  Compliance: HIGH
```

Fix the issues, run again, watch your score improve.

## Authentication

Offline diagnostics work without an account. For server-enhanced diagnostics (cross-file analysis, compliance scoring), sign up for the beta:

```bash
ails auth login       # GitHub Device Flow — authorize in browser
ails auth status      # Check current auth state
ails auth logout      # Remove stored credentials
```

## Commands

```bash
ails check                       # Validate instruction files
ails check -f json               # JSON output
ails check -f github             # GitHub Actions annotations
ails check --strict              # Exit 1 on any finding
ails check --agent claude        # Agent-specific rules only
ails check --exclude-dirs vendor # Exclude directory from scanning
ails check -v                    # Verbose: all findings with rule IDs

ails explain CORE:S:0001         # Explain a specific rule
ails heal                        # Auto-fix common violations
ails install                     # Install CLI to PATH + MCP server
ails update                      # Upgrade to latest version
ails version                     # Show version info
```

### Exit codes

| Code | Meaning                                             |
|------|-----------------------------------------------------|
| 0    | Success                                             |
| 1    | Findings found (strict mode)                        |
| 2    | Invalid input (bad path, unknown agent/format/rule) |

## Supported Agents

| Agent   | Base config                       | Rules                          | Skills                       | Agents                      | Other                                          |
|---------|-----------------------------------|--------------------------------|------------------------------|-----------------------------|------------------------------------------------|
| Claude  | `CLAUDE.md`, `.local.md`          | `.claude/rules/**/*.md`        | `.claude/skills/**/SKILL.md` | `.claude/agents/**/*.md`    | commands, output-styles, memory, MCP, settings |
| Codex   | `AGENTS.md`, `.override.md`       | `.codex/rules/*.rules`         | `.agents/skills/**/SKILL.md` | `.codex/agents/*.toml`      | hooks, config                                  |
| Copilot | `.github/copilot-instructions.md` | `.github/instructions/**/*.md` | `.github/skills/**/SKILL.md` | `.github/agents/*.agent.md` | hooks, prompts, MCP                            |
| Cursor  | `.cursorrules`, `AGENTS.md`       | `.cursor/rules/**/*.mdc`       | `.cursor/skills/**/SKILL.md` | `.cursor/agents/*.md`       | hooks, notepads, MCP, policy                   |
| Gemini  | `GEMINI.md`, `AGENTS.md`          | —                              | `.gemini/skills/**/SKILL.md` | `.gemini/agents/*.md`       | commands, extensions, settings                 |

Auto-detects which agents are present. Scans project-level, user-level (`~/`), and managed (`/etc/`) paths.

## Configuration

Project config in `.ails/config.yml`:

```yaml
default_agent: claude          # Default agent (run: ails config set default_agent claude)
exclude_dirs: [vendor, dist]   # Directories to skip
disabled_rules: [CORE:C:0010]  # Rules to disable
```

Set values via CLI: `ails config set <key> <value>`

### Global defaults

Global config in `~/.reporails/config.yml` applies to all projects. Project config overrides global.

```bash
ails config set --global default_agent claude
```

## GitHub Actions

Add `ails check` as a CI gate with inline PR annotations:

```yaml
name: Reporails
on:
  pull_request:
    paths: ['CLAUDE.md', '.claude/**', 'AGENTS.md', '.cursorrules']
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: reporails/cli/action
        with:
          strict: "true"
```

Or without the action:

```yaml
      - run: pip install reporails-cli && ails check . --format github --strict
```

## What It Checks

97 rules across five categories:

- **Structure** — File organization, discoverability, size limits, modularity
- **Content** — Clarity, specificity, reinforcement patterns, tech stack, domain terminology
- **Efficiency** — Token usage, instruction elaboration, formatting
- **Maintenance** — Versioning, review processes
- **Governance** — Security policies, credential protection, permissions

## Free vs Pro

| Feature                                                    | Free                  | Pro                             |
|------------------------------------------------------------|-----------------------|---------------------------------|
| Mechanical + structural rules                              | 97 rules, full detail | 97 rules, full detail           |
| Content-quality checks (embedding-based)                   | Full detail           | Full detail                     |
| Client checks (ordering, orphan, format, bold, scope)      | Full detail           | Full detail                     |
| Per-atom diagnostics (specificity, modality, brevity)      | Full detail           | Full detail                     |
| Interaction diagnostics (conflicts, competition, coupling) | Count per file        | Full detail (line, fix, effect) |
| Cross-file analysis (conflicts, repetition)                | Coordinates only      | Full                            |
| Compliance band + system score                             | —                     | Full                            |

Free tier requires no account. Pro shows you *how many* interaction problems exist and *where* cross-file conflicts are — enough to know if your instructions are working. Pro gives the full detail: which line, what to fix, and how strong the effect is.

## Performance

The embedding model is bundled in the wheel. First run may download the spaCy language model (~13 MB). Subsequent runs complete in under 2 seconds for typical projects.

## License

[BUSL 1.1](LICENSE) — converts to Apache 2.0 three years after each release.
