reporails-cli 0.0.2__tar.gz

reporails_cli-0.0.2/.claude/rules/backbone.md

@@ -0,0 +1,7 @@
+# Project Backbone
+
+Before running discovery (Glob, Grep, tree, find):
+
+- Check `.reporails/backbone.yml` for the location first
+- Only run discovery if backbone doesn't have the answer
+- Backbone is read once at session start - use that context

reporails_cli-0.0.2/.claude/rules/checks-readonly.md

@@ -0,0 +1,12 @@
+---
+paths: ["src/reporails_cli/bundled/**"]
+---
+
+# Bundled Config Files
+
+NEVER modify bundled config files without explicit human instruction.
+
+- `levels.yml` — Level definitions and rule-to-level mapping
+- `capability-patterns.yml` — OpenGrep patterns for capability detection
+
+These are CLI-owned orchestration logic, not framework rules.

reporails_cli-0.0.2/.claude/rules/documentation.md

@@ -0,0 +1,15 @@
+---
+paths: ["docs/*.md", "README.md"]
+---
+
+# User-Facing Documentation
+
+These files are read by people, not coding agents.
+
+- These files are for user-facing documentation, not AI agent instructions
+- Commands must be copy-pasteable and working (`ails check .`, not `reporails check .`)
+- Examples must reflect actual CLI behavior
+- Don't document features that don't exist yet
+- Keep installation/usage sections current with pyproject.toml
+- Use consistent terminology: "rules" not "checks" in user-facing text
+- When fixing errors, make targeted edits — don't rewrite sections and lose valid content

reporails_cli-0.0.2/.claude/rules/instruction-file-style.md

@@ -0,0 +1,13 @@
+---
+paths: ["CLAUDE.md", ".claude/rules/**"]
+---
+
+# Instruction File Style
+
+When writing or editing CLAUDE.md or .claude/rules/*.md files:
+
+- These files are for AI agent behavior, not user-facing documentation
+- State facts, commands, rules only
+- No meta-commentary ("this section explains...", "as mentioned above...")
+- Every line MUST be actionable or informative
+- Avoid redundant context that wastes tokens

reporails_cli-0.0.2/.claude/rules/specs.md

@@ -0,0 +1,13 @@
+---
+paths: ["docs/specs/**"]
+---
+
+# Specification Files
+
+Specs must accurately reflect the implementation.
+
+- Update specs when changing code behavior
+- Function signatures, return types, and interfaces must match code
+- Remove features from specs when removing from code
+- Add features to specs when adding to code
+- No aspirational content - document what exists, not what might exist

reporails_cli-0.0.2/.claude/rules/writing-rules.md

@@ -0,0 +1,29 @@
+---
+paths: [".claude/rules/**"]
+---
+
+# Writing Rule Files
+
+Rule files in `.claude/rules/` are loaded into Claude's context.
+
+## Format
+
+```markdown
+---
+paths: ["src/**/*.py"]  # Optional: scope to specific files
+---
+
+# Rule Title
+
+- Actionable instruction
+- Another instruction
+```
+
+## Guidelines
+
+- One concern per file (security separate from styling)
+- Keep under 500 lines - everything consumes tokens
+- Use descriptive filenames (`api-validation.md` not `rules1.md`)
+- Add `paths` frontmatter to reduce noise when not relevant
+- No paths = loads globally for all files
+- Content MUST be actionable, not explanatory

reporails_cli-0.0.2/.claude/settings.local.json

@@ -0,0 +1,66 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run ruff check:*)",
+      "Bash(uv run poe:*)",
+      "Bash(uv run python:*)",
+      "Bash(uv pip install:*)",
+      "Bash(uv run mypy:*)",
+      "Bash(uv run pytest:*)",
+      "Bash(uv run:*)",
+      "Bash(grep:*)",
+      "Bash(~/.local/share/reporails/opengrep scan:*)",
+      "Bash(ls:*)",
+      "Bash(~/.reporails/bin/opengrep scan:*)",
+      "Bash(fi)",
+      "Bash(done)",
+      "WebSearch",
+      "Bash(uv pip list:*)",
+      "Bash(uv sync:*)",
+      "Bash(git -C /home/cleverhoods/Projects/ai/reporail/cli status --short)",
+      "Bash(git -C /home/cleverhoods/Projects/ai/reporail/cli diff HEAD -- src/reporails_cli/core/cache.py .gitignore)",
+      "Bash(find:*)",
+      "Bash(python3:*)",
+      "WebFetch(domain:claudefa.st)",
+      "WebFetch(domain:www.anthropic.com)",
+      "Bash(gh api:*)",
+      "WebFetch(domain:claudelog.com)",
+      "Bash(xargs -I{} sh -c 'echo \"\"=== {} ===\"\" && grep severity {}')",
+      "Bash(echo:*)",
+      "Bash(gh repo view:*)",
+      "Bash(uv build:*)",
+      "Bash(unzip:*)",
+      "Bash(./scripts/link-rules.sh:*)",
+      "Bash(bash:*)",
+      "Bash(ln:*)",
+      "Bash(for f in checks/*/*.md)",
+      "Bash(do if [[ -L \"$f\" ]])",
+      "Bash(then echo \"=== $f ===\" head -20 \"$f\")",
+      "Bash(git -C /home/cleverhoods/Projects/ai/reporail/cli diff --stat HEAD)",
+      "Bash(python:*)",
+      "Bash(wc:*)",
+      "Bash(claude mcp list)",
+      "Bash(claude mcp list:*)",
+      "mcp__reporails__score",
+      "mcp__reporails__validate",
+      "Bash(git log:*)",
+      "Bash(~/.reporails/bin/opengrep:*)",
+      "Bash(PYTHONPATH=src python3:*)",
+      "Bash(1 --verbose)",
+      "Bash(__NEW_LINE_70733a4bdee3013b__ echo \"=== Without --no-git-ignore \\(git-tracked only\\) ===\")",
+      "Bash(head:*)",
+      "Bash(for f in ~/.reporails/rules/agents/claude/rules/*.yml)",
+      "Bash(do)",
+      "Bash(if ! grep -q \"paths:\" \"$f\")",
+      "Bash(then)",
+      "Bash(cat:*)",
+      "Bash(# Test scaling with rules that actually work echo \"\"=== 1 rule ===\"\" time ~/.reporails/bin/opengrep scan --sarif --config ~/.reporails/rules/agents/claude/rules/CLAUDE_M5-auto-generated-content-review.yml .)",
+      "Bash(# Test with --include to limit files echo \"\"=== 6 rules + whole directory ===\"\" time ~/.reporails/bin/opengrep scan --sarif \\\\ --config ~/.reporails/rules/agents/claude/rules/CLAUDE_M5-auto-generated-content-review.yml \\\\ --config ~/.reporails/rules/agents/claude/rules/CLAUDE_M7-rule-snippet-length.yml \\\\ --config ~/.reporails/rules/agents/claude/rules/CLAUDE_S4-hierarchical-memory.yml \\\\ --config ~/.reporails/rules/agents/claude/rules/CLAUDE_S5-path-scoped-rules.yml \\\\ .)",
+      "Bash(npx @modelcontextprotocol/inspector uv run ails-mcp)"
+    ]
+  },
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": [
+    "reporails"
+  ]
+}

reporails_cli-0.0.2/.claudeignore

@@ -0,0 +1,33 @@
+# Claude Code Ignore Patterns
+# Never read these files/directories.
+
+# Lock file
+uv.lock
+
+# Python cache & virtual environments
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.venv/
+
+# Build artifacts & caches
+.cache/
+.langgraph_api/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+
+# Version control
+.git/
+
+# IDE & editor
+.idea/
+
+# Environment & secrets
+.env
+.env.local
+.env.*.local

reporails_cli-0.0.2/.gitignore

@@ -0,0 +1,20 @@
+.idea
+.venv
+__pycache__
+
+# Framework docs (symlinked from framework repo)
+checks/*/*.md
+docs/capability-levels.md
+
+docs/research
+
+# Reporails caches (backbone.yml is committed, caches are not)
+.reporails/.cache/
+# Prevent stray .reporails in subdirectories
+*/.reporails/
+
+.env
+
+# Claude Code MCP config (machine-specific paths)
+.claude/mcp.json
+.mcp.json

reporails_cli-0.0.2/.mcp.json.example

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "reporails": {
+      "command": "uv",
+      "args": ["run", "--directory", "<PROJECT_ROOT>", "ails-mcp"]
+    }
+  }
+}

reporails_cli-0.0.2/.reporails/backbone.yml

@@ -0,0 +1,46 @@
+version: 1
+generated_at: '2026-01-25T17:43:08.682362+00:00'
+generator: ails discover
+target: /home/cleverhoods/Projects/ai/reporail/cli
+agents:
+  claude:
+    name: Claude (Anthropic)
+    instruction_files:
+    - CLAUDE.md
+    config_files:
+    - .claude/mcp.json
+    rule_files:
+    - .claude/rules/backbone.md
+    - .claude/rules/checks-readonly.md
+    - .claude/rules/documentation.md
+    - .claude/rules/instruction-file-style.md
+    - .claude/rules/specs.md
+    - .claude/rules/writing-rules.md
+components:
+  .claude.rules:
+    root: .claude/rules
+    instruction_files:
+    - .claude/rules/backbone.md
+    - .claude/rules/checks-readonly.md
+    - .claude/rules/documentation.md
+    - .claude/rules/instruction-file-style.md
+    - .claude/rules/specs.md
+    - .claude/rules/writing-rules.md
+    content_hash: sha256:bb2584d1cb25003d
+    imports:
+    - .reporails/backbone.yml
+  root:
+    root: .
+    instruction_files:
+    - CLAUDE.md
+    content_hash: sha256:ed36169e31ea423e
+    imports:
+    - .reporails/backbone.yml
+    - docs/specs/arch.md
+    - docs/specs/modules.md
+shared:
+- .reporails/backbone.yml
+stats:
+  total_instruction_files: 7
+  total_components: 2
+  total_references: 4

reporails_cli-0.0.2/CLAUDE.md

@@ -0,0 +1,89 @@
+# Reporails CLI
+
+AI instruction linter. Validates instruction files against community-maintained rules.
+
+**repoRAILS** = **Repo** **R**ecursive **AI** **L**inting**S**
+
+## Development Context
+
+You are developing the reporails CLI, not an end user.
+
+- **You**: modify source, run tests, read specs
+- **CLI end users**: install package, run `ails check`
+- **MCP end users**: use reporails via Claude Code
+
+Don't conflate these when discussing features, delivery, or documentation.
+
+## Session Start
+
+1. Read `.reporails/backbone.yml` for project structure
+2. Read `docs/specs/arch.md` for architecture decisions
+3. Read `docs/specs/modules.md` before modifying core modules
+
+## Quick Start
+```bash
+uv sync                    # Install dependencies
+uv run ails check .        # Validate (auto-downloads OpenGrep + framework)
+uv run ails map . --save   # Save backbone.yml
+```
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `ails check [PATH]` | Validate instruction files |
+| `ails check --refresh` | Force re-scan, ignore cache |
+| `ails check --quiet-semantic` | Suppress semantic rules message |
+| `ails check -f json` | JSON output (for scripts/MCP) |
+| `ails map [PATH]` | Discover project structure |
+| `ails map --save` | Save backbone.yml to .reporails/ |
+| `ails explain RULE_ID` | Show rule details |
+| `ails update` | Update framework to latest |
+| `ails version` | Show CLI and framework versions |
+
+## Project Structure
+```
+src/reporails_cli/
+├── core/           # Domain logic
+├── bundled/        # CLI-owned config (levels.yml, capability-patterns.yml)
+├── interfaces/     # CLI and MCP entry points
+└── formatters/     # Output adapters
+```
+
+See `docs/specs/arch.md` for full architecture.
+
+## Framework vs CLI
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| Rules | Downloaded to `~/.reporails/rules/` | What to check |
+| Levels | Bundled in `src/bundled/levels.yml` | How to score |
+| OpenGrep | Downloaded to `~/.reporails/bin/` | Pattern matching |
+
+## QA Commands
+
+| Command | Purpose |
+|---------|---------|
+| `uv run poe qa_fast` | Lint, type check, unit tests (pre-commit) |
+| `uv run poe qa` | Full QA including integration tests |
+| `uv run poe lint` | Ruff linter |
+| `uv run poe format` | Format code |
+| `uv run poe type` | Mypy type checking |
+| `uv run poe test_unit` | Unit tests only (fast, no OpenGrep) |
+| `uv run poe test_integration` | Integration tests (requires OpenGrep) |
+
+## Test Structure
+
+```
+tests/
+├── unit/           # Fast tests, no external dependencies
+└── integration/    # Requires OpenGrep binary
+```
+
+## Architecture
+
+- **Agent-Agnostic**: Detects Claude, Cursor, Windsurf, Copilot, Aider
+- **Claude Rules v0.0.1**: Linting rules currently for Claude only
+- **OpenGrep-Powered**: Deterministic pattern matching
+- **Two-Phase Detection**: Filesystem + content analysis for capability scoring
+- **Framework Separation**: CLI orchestrates, framework defines rules

reporails_cli-0.0.2/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 [Gábor Mészáros]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

reporails_cli-0.0.2/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: reporails-cli
+Version: 0.0.2
+Summary: Lint and score CLAUDE.md files — MCP-first AI context governance
+Project-URL: Homepage, https://github.com/reporails/cli
+Project-URL: Documentation, https://reporails.dev/docs
+Project-URL: Repository, https://github.com/reporails/cli
+Project-URL: Issues, https://github.com/reporails/cli/issues
+Author: Reporails Team
+License: Apache-2.0
+License-File: LICENSE
+Keywords: ai,claude,claude-code,context,lint,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: rich>=13.0.0
+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: 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
+
+Score your CLAUDE.md files. See what's missing. Improve your AI coding setup.
+
+## Quick Start
+```bash
+# Check your setup (auto-installs OpenGrep + rules on first run)
+uvx reporails-cli check .
+```
+
+That's it. You'll see:
+```
+╔══════════════════════════════════════════════════════════════╗
+║   SCORE: 8.1 / 10 (partial)  |  CAPABILITY: Governed (L5)    ║
+║   ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░         ║
+╚══════════════════════════════════════════════════════════════╝
+
+Violations:
+  CLAUDE.md (7 issues)
+    ○ MED C4.no-antipatterns :1    No NEVER or AVOID statements found
+    · LOW C12.no-version     :1    No version or date marker found
+    ...
+```
+
+Fix the issues, run again, watch your score improve.
+
+## What It Checks
+
+- **Structure** — File organization, size limits
+- **Content** — Clarity, completeness, anti-patterns
+- **Efficiency** — Token usage, context management
+- **Maintenance** — Versioning, review processes
+- **Governance** — Ownership, security policies
+
+## Capability Levels
+
+| Level | Name | What it means |
+|-------|------|---------------|
+| L1 | Absent | No instruction file |
+| L2 | Basic | Has CLAUDE.md |
+| L3 | Structured | Sections, imports |
+| L4 | Abstracted | .claude/rules/ directory |
+| L5 | Governed | Shared files, 3+ components |
+| L6 | Adaptive | Backbone + full governance |
+
+## MCP Integration (for Claude Code)
+
+For full semantic analysis, add the MCP server:
+```bash
+claude mcp add reporails -- uvx reporails-cli ails-mcp
+```
+
+Then ask Claude: "What ails claude?"
+
+## Commands
+```bash
+ails check .              # Score your setup
+ails check . -f json      # JSON output (for CI)
+ails check . --strict     # Exit 1 if violations (for CI)
+ails map .                # Show project structure
+ails map . --save         # Generate backbone.yml
+ails explain S1           # Explain a rule
+```
+
+## Rules
+
+Rules are maintained separately at [reporails/rules](https://github.com/reporails/rules).
+
+Want to add or improve rules? Contribute there.
+
+## License
+
+Apache 2.0