docs: add CLI reference and project overview, and update README links

README.md

@@ -111,6 +111,11 @@ cordon pass revoke <pass-id>
 Examples: `src/main.go`, `src/`, `**/*.env`, `git push --force*`.
 
 
+## Documentation
+
+- [CLI Reference](docs/cli-reference.md)
+- [Project Overview and Concepts](docs/project-overview-and-concepts.md)
+
 ## Build
 
 ### Dev Build & Install (Standard development workflow)

docs/cli-reference.md

@@ -0,0 +1,232 @@
+# Cordon CLI Reference
+
+This reference summarizes the `cordon` command tree, common workflows, and flags based on the current CLI implementation.
+
+## Global usage
+
+```bash
+cordon [command] [flags]
+```
+
+Global flags:
+
+- `--json` — output structured JSON (supported across user-facing commands)
+- `--mcp` — run Cordon as a stdio MCP server (root command mode)
+
+---
+
+## Top-level commands
+
+### `cordon init`
+Initializes Cordon in the current repository.
+
+What it does:
+- Creates `.cordon/policy.db`
+- Ensures user-level data DB in `~/.cordon/repos/<perimeter-id>/data.db`
+- Configures selected agent hooks/MCP integration
+- Optionally adds standard guardrails during first setup
+
+Flags:
+- `-y, --yes` — non-interactive defaults
+- `--agent` — reconfigure managed agent integrations for an existing installation
+
+Examples:
+
+```bash
+cordon init
+cordon init --yes
+cordon init --agent
+```
+
+### `cordon status`
+Shows repository, policy, auth, perimeter, and agent integration status.
+
+Examples:
+
+```bash
+cordon status
+cordon status --json
+```
+
+### `cordon log`
+Displays audit log entries with filter/export/stream options.
+
+Flags:
+- `--agent <id>`
+- `--allow`
+- `--deny`
+- `--granted`
+- `--pass`
+- `--file <substring>`
+- `--since <duration>` (for example `24h`, `7d`)
+- `--until <rfc3339-or-date>`
+- `--date <YYYY-MM-DD>`
+- `-f, --follow`
+- `-i, --interactive`
+- `--limit <n>`
+- `--export <csv-path>`
+
+Notes:
+- Some flags are mutually exclusive (`--date` vs `--since/--until`, `--follow` vs `--export`, etc.).
+- `--interactive` cannot be combined with `--json`.
+
+Examples:
+
+```bash
+cordon log --deny --since 24h
+cordon log --agent codex --file secrets --limit 100
+cordon log --export ./audit.csv
+```
+
+### `cordon sync`
+Syncs policy and audit data with Cordon Cloud.
+
+Flags:
+- `--background` — run detached sync with lockfile coordination
+
+Examples:
+
+```bash
+cordon sync
+cordon sync --background
+```
+
+### `cordon uninstall`
+Removes Cordon from the current repository.
+
+What it removes:
+- Cordon-managed hook and MCP config entries
+- Local `.cordon/` directory
+
+What it does not remove:
+- User-level data under `~/.cordon/`
+
+Example:
+
+```bash
+cordon uninstall
+```
+
+### `cordon version`
+Prints the CLI version.
+
+Example:
+
+```bash
+cordon version
+```
+
+---
+
+## Rule management
+
+### `cordon file`
+Manage protected file rules.
+
+Subcommands:
+- `cordon file add <pattern> [--allow] [--prevent-read]`
+- `cordon file list`
+- `cordon file remove <pattern>`
+
+Examples:
+
+```bash
+cordon file add "**/*.env" --prevent-read
+cordon file add "docs/**" --allow
+cordon file list
+cordon file remove "**/*.env"
+```
+
+### `cordon command`
+Manage protected command rules.
+
+Subcommands:
+- `cordon command add <pattern> [--allow]`
+- `cordon command list`
+- `cordon command remove <pattern>`
+
+Examples:
+
+```bash
+cordon command add "git push --force*"
+cordon command add "npm test*" --allow
+cordon command list
+cordon command remove "git push --force*"
+```
+
+---
+
+## Pass management
+
+### `cordon pass issue`
+Issues temporary access to a protected target.
+
+Usage:
+
+```bash
+cordon pass issue <target> [--duration 60m|24h|7d|1w|indefinite]
+```
+
+Flags:
+- `--duration` (default `60m`)
+- `--target` (alternative to positional target)
+
+### `cordon pass list`
+Lists active passes.
+
+Flags:
+- `--all` — include expired and revoked
+
+### `cordon pass revoke`
+Revokes an active pass.
+
+Usage:
+
+```bash
+cordon pass revoke <pass-id>
+```
+
+Examples:
+
+```bash
+cordon pass issue "src/secrets.go" --duration 24h
+cordon pass list
+cordon pass list --all
+cordon pass revoke 31d15ecd-19e3-41be-a20f-b74fe167013a
+```
+
+---
+
+## Authentication
+
+### `cordon auth login`
+Authenticate via device OAuth or machine token.
+
+Flags:
+- `--token <machine-token>`
+
+### `cordon auth status`
+Check current auth status and token validity.
+
+### `cordon auth logout`
+Clear local credentials and attempt server-side revocation.
+
+Examples:
+
+```bash
+cordon auth login
+cordon auth login --token "$CORDON_TOKEN"
+cordon auth status
+cordon auth logout
+```
+
+---
+
+## Hidden/internal commands
+
+The CLI also includes hidden/internal commands used by integrations and background tasks:
+
+- `cordon hook` — hook entrypoint for pre-tool enforcement
+- `cordon sessions extract` — transcript/session extraction utility
+
+These are intentionally hidden from normal command help output.

docs/project-overview-and-concepts.md

@@ -0,0 +1,54 @@
+# Project Overview and Concepts
+
+This document gives a practical overview of the Cordon CLI project and its core concepts.
+
+## What Cordon is
+
+Cordon is a policy enforcement layer for AI coding agents. It lets teams define repository-level protections and enforce them through native agent hooks before risky operations execute.
+
+In this repository:
+- `cli/` is the core product (policy logic, storage, hook enforcement, MCP server)
+
+## Core goals
+
+- **Prevent unsafe file and command operations by default**
+- **Allow controlled, temporary exceptions through passes**
+- **Provide audit visibility into allow/deny decisions**
+- **Work across multiple agent ecosystems with minimal user friction**
+
+## Primary concepts
+
+See the project README for canonical concept definitions and terminology.
+
+## High-level runtime architecture
+
+1. User runs a command (`init`, `file add`, `pass issue`, etc.)
+2. CLI resolves repo root and opens/migrates SQLite databases
+3. Policy mutation or query executes through internal store APIs
+4. Agent hooks or MCP server consume the same policy model at runtime
+5. Audit events are recorded to user-level data DB for log inspection and sync
+
+## Command groups and responsibilities
+
+- `init`, `uninstall`, `status`, `version`: lifecycle and diagnostics
+- `file`, `command`: policy authoring
+- `pass`: temporary overrides
+- `log`: audit visibility/export
+- `sync`, `auth`: cloud identity and policy/audit synchronization
+- hidden/internal commands (`hook`, `sessions extract`): integration/runtime internals
+
+## Design principles visible in this repo
+
+- **CLI-first architecture:** business logic lives in Go CLI, not extension clients
+- **Native integrations:** each agent platform is integrated through its own config/hook mechanism
+- **Safety defaults:** explicit policy and pass lifecycle, with auditable decisions
+- **Scriptable interface:** `--json` support for machine-readable CLI consumption
+- **Incremental compatibility:** hooks are appended without destroying unrelated user config
+
+## Suggested reading order for contributors
+
+1. Root `README.md` for product-level behavior and command map
+2. `cli/README.md` for package layout
+3. `cli/cmd/` for command entrypoints and flag contracts
+4. `cli/internal/store/` for schema and policy semantics
+5. `cli/internal/hook/` and `cli/internal/agents/` for enforcement/integration behavior