# Project Context CLI Reference

The `agents project context` commands manage per-project context policies
that control what resources and files are visible during each ACMS phase,
and provide tools to inspect and simulate the ACMS pipeline state.

## Overview

Context policies use **view inheritance**:

| Phase      | Inherits from |
|------------|---------------|
| default    | (none)        |
| strategize | default       |
| execute    | strategize    |
| apply      | execute       |

An empty policy defaults to including everything.

---

## `agents project context set`

Persist a context policy view and ACMS pipeline configuration for a project.

### Usage

```
agents project context set PROJECT [OPTIONS]
```

### Arguments

| Argument  | Description                  |
|-----------|------------------------------|
| `PROJECT` | Project namespaced name      |

### Options

#### View Options

| Option               | Type      | Description                              |
|----------------------|-----------|------------------------------------------|
| `--view`, `-v`       | `str`     | Phase view: default, strategize, execute, apply (default: default) |
| `--include-resource`  | `str`     | Resource pattern to include (repeatable) |
| `--exclude-resource`  | `str`     | Resource pattern to exclude (repeatable) |
| `--include-path`      | `str`     | File path glob to include (repeatable)   |
| `--exclude-path`      | `str`     | File path glob to exclude (repeatable)   |
| `--max-file-size`     | `int`     | Max file size in bytes (None = no limit) |
| `--max-total-size`    | `int`     | Max total context size in bytes          |
| `--clear`             | `flag`    | Clear (reset) the view for the phase     |

#### ACMS Pipeline Options

| Option                  | Type    | Default  | Description                                    |
|-------------------------|---------|----------|------------------------------------------------|
| `--hot-max-tokens`       | `int`   | 8000     | Max tokens for the hot tier context window      |
| `--warm-max-decisions`   | `int`   | 500      | Max decisions for the warm tier                 |
| `--cold-max-decisions`   | `int`   | 5000     | Max decisions for the cold tier                 |
| `--query-limit`          | `int`   | None     | Max number of fragments per query               |
| `--summarize/--no-summarize` | `bool` | True  | Enable or disable context summarization         |
| `--summary-max-tokens`   | `int`   | None     | Max tokens for context summaries                |
| `--strategy`             | `str`   | (none)   | Preferred context strategy (repeatable)         |
| `--default-breadth`      | `int`   | 2        | Default breadth for context retrieval           |
| `--default-depth`        | `str`   | 3        | Default depth (integer or named level)          |
| `--skeleton-ratio`       | `float` | 0.2      | Skeleton compression ratio (0.0-1.0)            |
| `--temporal-scope`       | `str`   | current  | Temporal scope: current, recent, or all         |
| `--auto-refresh/--no-auto-refresh` | `bool` | True | Auto-refresh context on resource changes   |

#### Output Options

| Option          | Type  | Description                              |
|-----------------|-------|------------------------------------------|
| `--format`, `-f`| `str` | Output format (json, yaml, plain, table, rich) |

### Examples

```bash
# Set default view with resource filters
agents project context set local/my-app \
  --view default \
  --include-resource "db-*" \
  --exclude-resource "db-test"

# Set strategize view with path filters
agents project context set local/my-app \
  --view strategize \
  --include-path "src/**/*.py" \
  --exclude-path "*.pyc"

# Set size limits
agents project context set local/my-app \
  --max-file-size 1048576 \
  --max-total-size 10485760

# Clear execute view (inherit from strategize)
agents project context set local/my-app --view execute --clear

# Configure ACMS pipeline options
agents project context set local/my-app \
  --hot-max-tokens 4000 \
  --warm-max-decisions 200 \
  --temporal-scope recent \
  --no-auto-refresh

# Set preferred strategies
agents project context set local/my-app \
  --strategy breadth_first \
  --strategy depth_first

# Adjust skeleton compression
agents project context set local/my-app \
  --skeleton-ratio 0.5 \
  --default-breadth 5 \
  --default-depth 7
```

---

## `agents project context show`

Display the context policy and ACMS pipeline configuration for a project.

### Usage

```
agents project context show PROJECT [OPTIONS]
```

### Arguments

| Argument  | Description             |
|-----------|-------------------------|
| `PROJECT` | Project namespaced name |

### Options

| Option          | Type  | Description                                      |
|-----------------|-------|--------------------------------------------------|
| `--view`, `-v`  | `str` | Show resolved view for a specific phase           |
| `--format`, `-f`| `str` | Output format (json, yaml, plain, table, rich)   |

### Output

The `show` command displays:

- **View configuration** for each phase (or the resolved view for a specific phase)
- **ACMS Pipeline Config** including hot/warm/cold tier budgets, summarization settings,
  strategies, temporal scope, and auto-refresh status

### Examples

```bash
# Show all views and ACMS config
agents project context show local/my-app

# Show resolved view for execute phase
agents project context show local/my-app --view execute

# JSON output (includes acms_config key)
agents project context show local/my-app --format json
```

---

## `agents project context inspect`

Inspect the effective context state for a project by querying the ACMS
tier service. Displays current fragment distribution across tiers, tier
metrics, budget utilisation, and per-actor visibility.

### Usage

```
agents project context inspect PROJECT [OPTIONS]
```

### Arguments

| Argument  | Description             |
|-----------|-------------------------|
| `PROJECT` | Project namespaced name |

### Options

| Option            | Type  | Description                                    |
|-------------------|-------|------------------------------------------------|
| `--view`, `-v`    | `str` | Phase view to inspect                          |
| `--strategy`      | `str` | Filter fragments by strategy name              |
| `--focus`         | `str` | UKO URIs to focus on (repeatable)              |
| `--breadth`       | `int` | Override breadth for context retrieval          |
| `--depth`         | `str` | Override depth (integer or named level)         |
| `--format`, `-f`  | `str` | Output format (json, yaml, plain, table, rich) |

### Output

The `inspect` command displays:

- **Tier Metrics** — project-scoped hot/warm/cold fragment counts, service-level hit/miss rates
- **Tier Budget** — configured max tokens (hot) and max decisions (warm, cold)
- **Project Fragments** — total count and breakdown by tier for the project
- **Actor Visibility** — how many fragments each actor role (strategist, executor, reviewer) can see
- **Fragment Details** — first 20 fragments with IDs, tiers, token counts, and access metadata
- **ACMS Config** — the project's pipeline configuration

### Examples

```bash
# Inspect all tiers for a project
agents project context inspect local/my-app

# Inspect with JSON output
agents project context inspect local/my-app --format json

# Inspect a specific phase view
agents project context inspect local/my-app --view strategize
```

---

## `agents project context simulate`

Run a dry-run context window assembly for a project. Creates a simulated
`AssembledContext` using the project's ACMS configuration and available
tier fragments.

### Usage

```
agents project context simulate PROJECT [OPTIONS]
```

### Arguments

| Argument  | Description             |
|-----------|-------------------------|
| `PROJECT` | Project namespaced name |

### Options

| Option            | Type  | Description                                    |
|-------------------|-------|------------------------------------------------|
| `--view`, `-v`    | `str` | Phase view for simulation                      |
| `--budget`        | `int` | Token budget override                          |
| `--focus`         | `str` | UKO URIs to focus on (repeatable)              |
| `--strategy`      | `str` | Preferred strategies (repeatable)              |
| `--format`, `-f`  | `str` | Output format (json, yaml, plain, table, rich) |

### Output

The `simulate` command displays:

- **Summary** — total tokens, budget usage percentage, strategies used, fragment count, context hash
- **Fragment Table** — each assembled fragment with UKO node, token count, relevance score, depth, and strategy. When `--focus` is provided, only fragments matching the focus URIs are included.
- **ACMS Config** — the project's pipeline configuration used for the simulation

### Examples

```bash
# Simulate with default settings
agents project context simulate local/my-app

# Simulate with custom budget
agents project context simulate local/my-app --budget 4000

# Simulate for a specific phase with strategy hints
agents project context simulate local/my-app \
  --view strategize \
  --strategy breadth_first

# JSON output for programmatic consumption
agents project context simulate local/my-app --format json
```