# @typescape-ai/cli

Typescape CLI — agent-first review, finding, and rules workflows for Markdown.

## Requirements

- [Bun](https://bun.sh/) 1.3.10+

## Installation

```bash
# Global install with Bun
bun add -g @typescape-ai/cli

# Or install in a project with Bun
bun add -D @typescape-ai/cli
```

Run without installing:

```bash
bunx @typescape-ai/cli
```

## Quick Start

1. Initialize config in your repo:

```bash
typescape init
```

2. Set your API token:

```bash
export TYPESCAPE_API_KEY=your-token-here
```

3. Fetch the canonical rules bundle for the content you are about to review:

```bash
typescape rules get --properties '{"doc_type":"procedure"}'
```

`rules get --format text` now prepends a metadata block with the bundle
`compiled_hash`, freshness, and applicability basis. Use plain `--format text`
for the canonical human/agent-readable bundle, or `--format structured` /
`--format json` for machine-oriented payloads.

4. Create a review:

```bash
typescape review create --file docs/README.md --reviewer alice@example.com
```

5. Optionally request a fast advisory pass:

```bash
typescape rules check --file docs/README.md --properties '{"doc_type":"procedure"}'
```

`rules check` is advisory. The canonical loop is:

1. `typescape rules get`
2. the agent reads the draft and reasons over it
3. `typescape finding create`

Its exit codes are still useful for automation: `0` means the advisory pass ran
with no blocking signals, `1` means it returned blocking signals, `2` is
validation, `3` is network/auth, and `4` is a server error.

6. Record findings in plain language:

```bash
typescape finding create --review sess_abc123 --body "Never mention supplements in patient-facing copy."
```

7. Export feedback:

```bash
typescape review export --review rev_xxx
```

`review export` defaults to the canonical `export.v2` contract. Explicit
`--schema v1` runtime requests are retired; use versioned views like
`response_matrix.v1` only when you intentionally need that bounded
compatibility shape.

## Commands

### Review Management

| Command            | Description                                                  |
| ------------------ | ------------------------------------------------------------ |
| `review create`    | Create a new review                                          |
| `review get`       | Get review details                                           |
| `review list`      | List reviews with filters                                    |
| `review export`    | Export review feedback as canonical `export.v2` JSON         |
| `review status`    | Get policy verdict for a review                              |
| `review close`     | Close a review                                               |
| `review supersede` | Create a new content-review revision from an existing review |

### Findings & Comments

| Command            | Description                                          |
| ------------------ | ---------------------------------------------------- |
| `finding create`   | Record a plain-language finding on a review or block |
| `finding comment`  | Post a reply to an existing finding                  |
| `finding list`     | List findings for a review                           |
| `finding resolve`  | Resolve a finding                                    |
| `finding decision` | Record a decision on a finding                       |
| `finding evidence` | Attach evidence to a finding                         |

### Rules

| Command           | Description                                                  |
| ----------------- | ------------------------------------------------------------ |
| `rules list`      | List applicable rules                                        |
| `rules get`       | Get the canonical compiled rules bundle for agent reasoning  |
| `rules check`     | Request an optional server-side advisory pass                |
| `rules documents` | List canonical rule-document truth                           |
| `rules import`    | Import markdown into a draft rule review                     |
| `rules publish`   | Publish a draft rule review; it is not live until activation |
| `rules revise`    | Create or revise a working draft for a rule review           |
| `rules deprecate` | Deprecate a published rule review                            |
| `rules candidate` | Create, inspect, and transition release candidates           |
| `rules dashboard` | Inspect supplemental rule diagnostics                        |
| `rules signal`    | Submit, inspect, and triage governance signals               |
| `coverage`        | Check section coverage against active rules                  |

### Review & Approval

| Command              | Description                               |
| -------------------- | ----------------------------------------- |
| `approval request`   | Request approval from specified approvers |
| `approval decide`    | Record an approval decision               |
| `review-ref get`     | Get review reference detail and lineage   |
| `review-ref create`  | Create a stable review reference          |
| `review-ref resolve` | Resolve a review ref to its current head  |
| `review-ref advance` | Advance a review ref to a new head        |
| `proposed-changes`   | Manage proposed changes                   |
| `checks run`         | Run quality checks (DocLint)              |
| `search`             | Search reviews by title and file path     |
| `verify export`      | Validate an export against the schema     |

### Orchestration & Collections

| Command             | Description                                          |
| ------------------- | ---------------------------------------------------- |
| `repo list`         | List connected repositories                          |
| `repo connect`      | Connect a repository by Git URL                      |
| `repo branches`     | List branches for a connected repository             |
| `project create`    | Create a new upload-backed project                   |
| `project list`      | List projects                                        |
| `project get`       | Get project detail                                   |
| `project update`    | Update project metadata                              |
| `project delete`    | Start project deletion                               |
| `project move`      | Declare a project file-path move                     |
| `project upload`    | Upload files into a project batch                    |
| `template create`   | Create a reusable review template                    |
| `template list`     | List review templates                                |
| `template get`      | Get template detail                                  |
| `review-set create` | Create a multi-file review set                       |
| `review-set list`   | List review sets                                     |
| `review-set get`    | Get review set overview                              |
| `review-set update` | Update review set title or lifecycle state           |
| `review-set export` | Export a review set using canonical schema=v2        |
| `review-set status` | Evaluate aggregate review-set policy status          |
| `collection create` | Create a new collection                              |
| `collection add`    | Add reviews to a collection                          |
| `collection get`    | Get one collection with member reviews               |
| `collection list`   | List collections                                     |
| `collection update` | Update collection metadata or archive state          |
| `collection delete` | Archive a collection via the canonical PATCH surface |

### Auth & Configuration

| Command           | Description                                 |
| ----------------- | ------------------------------------------- |
| `init`            | Create `.typescape/config.yaml`             |
| `config validate` | Validate config and show effective settings |
| `token generate`  | Generate a new API token                    |
| `auth login`      | Authenticate with the Typescape server      |
| `smoke-test`      | End-to-end sanity check                     |
| `anchors`         | Inspect block anchors for a file            |
| `ids`             | Generate Typescape IDs                      |

## Configuration

Create `.typescape/config.yaml`:

```yaml
version: 1
server:
  base_url: https://your-typescape-instance.com
```

Set `TYPESCAPE_API_KEY` environment variable with your operator token.

The old top-level `guidelines`, `gci`, and `advisory` command families are
removed. New automation should use the `rules` command family directly,
including `rules signal` for governance-signal workflows. Explicit `export.v1`
runtime requests are retired; first-party exports default to `export.v2`,
while `response_matrix.v1` remains a bounded compatibility view.

## License

MIT