# Bilt

> Deterministic production-readiness checks for AI-built software. Catches what your coding agent missed before you ship.

- **Package Name**: `bilt-toolkit` (npm: https://www.npmjs.com/package/bilt-toolkit)
- **CLI Binary**: `bilt` (or `npx bilt`)
- **Website**: https://bilt.nogs.dev
- **Docs URL**: https://bilt.nogs.dev/docs
- **Complete LLM Text**: https://bilt.nogs.dev/llms-full.txt
- **Machine API Specification**: https://bilt.nogs.dev/docs/api.json
- **Task Definitions & CI/CD**: https://bilt.nogs.dev/docs/task-definitions.json

## What is Bilt?

Bilt is the automated, deterministic verification gate for software generated by developers and AI coding agents (Claude Code, Cursor, Windsurf, Devin, OpenAI Codex, Antigravity).

Bilt asks the crucial question before you ship:
**"What did this developer or AI coding agent miss before exposing this app to real users?"**

Instead of vanity metrics or a fake "100% secure" score, Bilt provides:
1. **Deterministic Static Verification**: AST traversal, Shannon entropy (H > 4.5), and data-flow analysis. AI never decides whether code passes or fails.
2. **Guided Review Procedures**: Checklists and route mapping for multi-tenancy (IDOR) and billing vectors that cannot be verified by regex alone.
3. **Machine-Readable Agent Interfaces**: Dedicated JSON schemas (`--format agent`), deterministic exit codes (0-4), anti-tamper git verification, and loop budget protection.

## Core Commands Quick Reference (18 Commands)

| Command | Category | Purpose | Exit Codes |
| :--- | :--- | :--- | :--- |
| `bilt check [dir]` | Gate | Evaluates repository against 14-category taxonomy | 0, 1, 2, 3 |
| `bilt verify [dir]` | Gate | Strict diff verification against git base branch with anti-tamper and loop budget | 0, 1, 2, 3, 4 |
| `bilt scan [dir]` | Static Scan | Audits secrets, env divergence, and Shannon entropy leaks | 0, 1, 2 |
| `bilt api-scan [dir]` | Static Scan | Static API checks: mass assignment, method allowlists | 0, 1, 2 |
| `bilt design-check [dir]` | Design | Audits UI for generic AI patterns, authenticity, and accessibility | 0, 1, 2, 4 |
| `bilt fix [dir]` | Remediation | Applies safe automated repairs and creates atomic rollback snapshots | 0, 2 |
| `bilt undo [dir]` | Remediation | Instant atomic rollback of previous fix in sub-2ms | 0, 2 |
| `bilt watch [dir]` | Daemon | Real-time background file monitor daemon (alias: `bilt live`) | 0, 2 |
| `bilt baseline create` | Baseline | Captures existing technical debt into `.bilt/baseline.json` | 0, 2 |
| `bilt mcp` | Protocol | Starts Model Context Protocol server for Claude Desktop / Cursor / Windsurf | 0, 3 |
| `bilt prompt` | Agent Setup | Prints standardized system instructions for AI coding agents | 0, 2 |
| `bilt init [dir]` | Scaffolding | Scaffolds `.biltrc.json`, `.env.example`, and `AGENTS.md` | 0, 2 |
| `bilt accept-risk <id>` | Governance | Formally accepts operational risk for non-mandatory items | 0, 2 |
| `bilt explain [cat]` | Education | Explains readiness concepts and guided inspection checklists | 0, 2 |
| `bilt doctor [dir]` | Diagnostics | Holistic repository health diagnostics & OWASP map | 0, 2 |
| `bilt report [dir]` | Reporting | Exports structured health reports to markdown or JSON | 0, 2 |
| `bilt plugin <action>` | Plugins | Manages custom AST rules (`list`, `create`, `install`) | 0, 2 |
| `bilt welcome` | Onboarding | Interactive onboarding wizard (aliases: `guide`, `onboarding`) | 0, 2 |
| `bilt ai` & `bilt ask` | AI Explainer | Privacy-first AI explainer with universal token redaction | 0, 2 |

## Deterministic Exit Codes

- `0` (`pass`): All checks passed. Proceed to commit, push, or merge PR.
- `1` (`fail`): Hard security violation, mandatory invariant failed, or config file tampering. Agent must remediate.
- `2` (`needs_review`): Medium-precision heuristic requiring human review. Non-blocking unless `--strict`.
- `3` (`error`): Command syntax error, invalid flags, or AST parse failure.
- `4` (`escalate`): Loop budget exceeded or runaway loop detected. Agent MUST halt retries immediately.

## The 14 Production Readiness Categories

### The 6 Mandatory Invariant Categories (Non-Bypassable, No Risk Acceptance Allowed)
1. `secrets-and-env`: Hardcoded keys, exposed `.env`, client prefix leaks (`NEXT_PUBLIC_SECRET`), missing `.env.example`.
2. `auth`: Plaintext passwords, weak hashing (MD5/SHA1), unverified JWT decode, missing expiration, auth stubs.
3. `authorization`: Client-controlled roles (`req.body.isAdmin`), IDOR, missing server-side tenancy checks.
4. `input-validation`: SQL injection, command execution (`exec`), path traversal, unsafe HTML injection.
5. `api-abuse-and-cost`: Unauthenticated endpoints calling paid AI APIs (OpenAI, Anthropic), missing rate limits.
6. `database`: Client-side database driver imports, unencrypted DB strings, missing backup policies.

### The 8 Secondary Categories (Risk Acceptance Allowed with --reason and --owner)
7. `dependencies`: Missing lockfiles, known vulnerabilities, floating version ranges.
8. `error-handling-logs`: Raw stack traces sent to HTTP clients, secrets printed to stdout.
9. `transport-and-headers`: Insecure CORS (`origin: *` with credentials), missing security headers.
10. `deploy-config`: Production containers with `NODE_ENV=development`, exposed source maps.
11. `file-uploads`: Unrestricted file uploads, missing MIME validation, bucket isolation.
12. `payments`: Missing webhook cryptographic signature verification (`stripe.webhooks.constructEvent`).
13. `privacy-and-pii`: Sensitive PII exposure, unencrypted customer records.
14. `monitoring-rollback`: Production error tracking SDKs (Sentry, Datadog), health check endpoints.

## AI Agent Integration

### Agent Mode Command
```bash
npx bilt check --format agent
```

### Setup Prompt for AI Coding Agents
Copy and paste into Cursor, Windsurf, Claude Code, or Copilot:
```text
Run `npx bilt check --format agent` to evaluate repository readiness.
If exit code is 1, read `findings[].agent_action` and fix the code directly.
Never weaken .biltrc.json or add blanket ignores to force a pass.
If exit code is 4, halt retries and report the blocker to the human maintainer.
```

### Native MCP Server Configuration
Add to `claude_desktop_config.json` or Cursor MCP settings:
```json
{
  "mcpServers": {
    "bilt": {
      "command": "npx",
      "args": ["-y", "bilt-toolkit", "mcp"]
    }
  }
}
```

## Documentation Links

- [Complete All-In-One Documentation (Markdown)](https://bilt.nogs.dev/docs.md)
- [Full LLM Markdown Guide](https://bilt.nogs.dev/llms-full.txt)
- [Machine API Specification (JSON)](https://bilt.nogs.dev/docs/api.json)
- [Task Definitions & CI/CD Workflows (JSON)](https://bilt.nogs.dev/docs/task-definitions.json)
- [Production Readiness Guide](https://bilt.nogs.dev/docs/production-readiness.md)
- [Security Analysis Guide](https://bilt.nogs.dev/docs/security-analysis.md)