@archpilotlabs/archpilot 0.0.18 → 0.1.0

package/README.md

@@ -8,7 +8,7 @@
   Architecture guardrails for AI-native software development
 </p>
 
-ArchPilot validates your repository against architecture rules and helps engineering teams move faster with AI-assisted development-without sacrificing architectural integrity.
+ArchPilot validates your repository against architecture rules, helping engineering teams move faster with AI-assisted development without sacrificing architectural integrity.
 
 **Your AI writes code. ArchPilot protects architecture.**
 
@@ -20,7 +20,7 @@ ArchPilot makes architecture **visible, enforceable, and measurable** as your sy
 
 ---
 
-## 🧭 Why this exists
+## Why this exists
 
 Most teams rely on documentation or tribal knowledge to maintain architecture.
 
@@ -28,83 +28,99 @@ Over time, boundaries blur, dependencies leak, and architectural decisions drift
 
 ArchPilot turns architecture into something you can **actually validate, enforce, and track continuously**.
 
-AI accelerates code delivery-but architectural drift accelerates too.
+AI accelerates code delivery but architectural drift can accelerate too.
 
 ArchPilot gives teams deterministic architecture guardrails in local development, CI, and governance workflows.
 
 ---
 
-## 🚀 What it does
+## What it does
 
 ArchPilot turns architecture into something you can actually run and verify:
 
-* Validate module boundaries and dependencies
-* Enforce architecture rules and contracts
-* Detect architectural drift over time
-* Generate architecture scores and reports
-* Surface architecture feedback in PRs and CI
+- Validate architecture across modern application stacks
+- Validate module boundaries and dependency governance
+- Enforce architecture rules and contracts
+- Detect architectural drift over time
+- Generate architecture scores and reports
+- Surface architecture feedback in local development, PRs, and CI
 
 No runtime agents. No external services. Fully deterministic and local-first.
 
+ArchPilot works alongside GitHub Copilot, Claude Code, Codex, Cursor, and other AI coding tools by continuously validating architectural boundaries before architectural drift becomes technical debt.
+
 ---
 
-## 🧩 Supported Stacks
+## Supported Stacks
 
-ArchPilot supports **practical deterministic architecture detection** across modern application stacks.
+ArchPilot provides **deterministic architecture validation** across modern application stacks using framework-aware analysis and explicit architectural evidence.
 
 ### Backend
 
-* Node.js / TypeScript
-* NestJS
-* Express.js
-* Java
-* Spring / Spring Boot
-* Kotlin
-* FastAPI
-* Django
-* Flask
-* PHP
-* Laravel
-* Go
-* .NET
-* Ruby on Rails
+Framework-aware validation
+
+- Spring / Spring Boot
+- NestJS
+- Express.js
+- FastAPI
+- Laravel
+- ASP.NET
+- Go
+
+Language-aware validation
+
+- Java
+- Node.js / TypeScript
+- PHP
+- Python
+
+Framework detection
+
+- Kotlin
+- Django
+- Flask
+- Ruby on Rails
 
 ### Frontend
 
-* React
-* Next.js
-* Angular
-* Vue
+- React
+- Next.js
+- Angular
+- Vue
+
+### Infrastructure Context
+
+- Terraform
+- Ansible
 
-### Infrastructure
+Infrastructure repositories are detected as part of repository architecture discovery. Full architecture validation currently focuses on application stacks.
 
-* Terraform
-* Ansible
+ArchPilot automatically detects supported stacks from repository evidence including framework markers, dependency metadata, manifests, project layout, source structure, and framework-specific constructs.
 
-ArchPilot detects stack shape from practical repository evidence - framework markers, manifests, project layout, and source structure - then applies conservative architecture discovery defaults locally.
+Validation remains deterministic and framework-aware. When evidence is ambiguous, ArchPilot intentionally prefers conservative findings over speculative analysis.
 
 **No cloud scanning. No remote indexing. Deterministic local validation.**
 
 ---
 
-## ☁️ Local-first. Cloud-powered.
+## Local-first. Cloud-powered.
 
 Start locally in minutes:
 
-* Offline validation
-* Local reports and artifacts
-* PR review markdown
-* CI validation
-* Deterministic architecture checks
+- Offline validation
+- Local reports and artifacts
+- PR review markdown
+- CI validation
+- Deterministic architecture checks
 
 Then connect to **ArchPilot Cloud** to unlock:
 
-* Repository history and trends
-* Findings dashboards
-* Team ownership and governance workflows
-* Shared policies and exceptions
-* Organization-wide architecture visibility
-* Continuous governance across repositories
+- Repository history and trends
+- Findings dashboards
+- Team ownership and governance workflows
+- Shared policies and exceptions
+- Organization-wide architecture visibility
+- Continuous governance across repositories
 
 ```bash
 archpilot cloud status
@@ -114,14 +130,15 @@ archpilot cloud disconnect
 
 Cloud setup only asks for your API token.
 
-ArchPilot uses the canonical production API automatically-no server URL setup required for normal use.
+ArchPilot uses the canonical production API automatically; no server URL setup is required for normal use.
+
 Learn more:
 
 https://archpilot.org/docs
 
 ---
 
-## 📦 Installation
+## Installation
 
 Install globally:
 
@@ -137,7 +154,7 @@ npx @archpilotlabs/archpilot --help
 
 ---
 
-## ⚡ Quick Start
+## Quick Start
 
 ### 1. Initialize architecture
 
@@ -183,24 +200,24 @@ Applies safe, deterministic fixes for missing architecture artifacts.
 archpilot validate --ci
 ```
 
-* Fails only on real architecture violations
-* Keeps setup issues separate from architecture quality
+- Fails only on real architecture violations
+- Keeps setup issues separate from architecture quality
 
 ---
 
-## 🧑‍💻 CLI vs VS Code Extension
+## CLI vs VS Code Extension
 
 ArchPilot works in two ways:
 
-* **CLI (this package)** → validation, CI, automation
-* **VS Code Extension** → visual inspector, guided workflows, and architecture exploration
+- **CLI (this package)** - validation, CI, automation
+- **VS Code Extension** - visual inspector, guided workflows, and architecture exploration
 
 Both use the same validation engine and produce identical results.
 The extension enhances developer experience, but is not required.
 
 ---
 
-## 🧠 Key Concepts
+## Key Concepts
 
 ### Architecture Health Score
 
@@ -212,13 +229,13 @@ Tracks completeness of configuration and onboarding.
 
 ### Findings
 
-* **violation** → real architecture issue
-* **setup-gap** → missing config / skipped checks
-* **guidance** → non-blocking recommendation
+- **violation** - real architecture issue
+- **setup-gap** - missing config / skipped checks
+- **guidance** - non-blocking recommendation
 
 ---
 
-## 🔍 Core Commands
+## Core Commands
 
 ```bash
 archpilot init
@@ -247,37 +264,58 @@ archpilot governance upload
 
 ---
 
-## ⚙️ Core Capabilities
+## Core Capabilities
+
+- Architecture-as-code (`.archpilot/`)
+- Smart Init architecture discovery
+- Cross-stack architecture validation
+- Dependency governance and module contracts
+- ADR (Architecture Decision Record) support
+- Drift detection and history tracking
+- PR review and CI integration
+- Architecture scoring and reporting
+
+---
+
+## Deterministic by Design
+
+ArchPilot intentionally avoids speculative code analysis.
+
+Findings are produced from explicit architectural evidence such as:
+
+- Framework annotations and decorators
+- Dependency relationships
+- Route and API definitions
+- Authorization constructs
+- Transaction boundaries
+- ORM and query APIs
+- Event and messaging infrastructure
+- Architecture configuration and contracts
 
-* Architecture-as-code (`.archpilot/`)
-* Dependency validation and module contracts
-* ADR (Architecture Decision Record) support
-* Drift detection and history tracking
-* PR review and CI integration
-* Architecture scoring and reporting
+When evidence is ambiguous, ArchPilot prefers not to report a finding rather than generating false positives.
 
 ---
 
-## 🎯 Philosophy
+## Philosophy
 
 ArchPilot is built on four principles:
 
-* Architecture should be explicit
-* Rules should be executable
-* Validation should be deterministic
-* Feedback should be continuous
+- Architecture should be explicit
+- Rules should be executable
+- Validation should be deterministic
+- Feedback should be continuous
 
 ---
 
-## 📄 License
+## License
 
 Proprietary. See LICENSE file for details.
 
 ---
 
-## 🌐 Learn More
+## Learn More
 
-* Website: https://archpilot.org
-* Documentation: https://archpilot.org/docs
+- Website: https://archpilot.org
+- Documentation: https://archpilot.org/docs
 
 ---