# GSP Commands 0.1

## init

Create a minimal GSP project.

```bash
gsp init [path] [--name project-name] [--entry project.entry] [--force]
```

Generated structure:

```text
project/
  gsp.manifest
  design/
    project.entry.gsp
```

## ai-init

Create AI-facing usage files for a GSP project.

```bash
gsp ai-init [--root .] [--agents] [--skill generic|codex] [--all] [--force]
```

Default output:

```text
README.md
AI_USAGE.md
```

Optional output:

```text
AGENTS.md
skills/gsp/SKILL.md
.codex/skills/gsp/SKILL.md
```

## version

Print toolkit and protocol versions.

```bash
gsp version
gsp version --json
```

## completion

Print or install shell completion scripts.

```bash
gsp completion powershell
gsp completion bash
gsp completion zsh
gsp completion fish
gsp completion install powershell
```

Completion covers subcommands, common flags, enum values, and GSP ids from `gsp index --root .`.

## validate

Validate GSP files and references.

```bash
gsp validate [--root .] [--out report.json]
```

## index

Build a stable GSP index.

```bash
gsp index [--root .] [--out index.json]
```

## trace

Inspect relation chains from one GSP id.

```bash
gsp trace <id> [--root .] [--depth 3] [--out trace.json]
```

## flatten

Expand one GSP id into a flat context.

```bash
gsp flatten <id> [--root .] [--depth 3] [--include-type a,b] [--exclude-type a,b] [--out flattened.json]
```

## pack

Create a compact AI context pack.

```bash
gsp pack <id> [--root .] [--for implement] [--stage implement] [--depth 3] [--budget 12000] [--format json|md|canvas] [--out context-pack.json]
```

The `--for` value describes the task intent:

```text
design
implement
review
test
acceptance
handoff
inspect
```

Formats:

```text
json      Machine-readable context pack.
md        Human-readable and AI-readable context pack.
canvas    Obsidian JSON Canvas for included GSP relations.
```

## impact

Find direct and indirect GSPs affected by a GSP id.

```bash
gsp impact <id> [--root .] [--depth -1] [--format json|md|canvas] [--out impact.json]
```

Formats:

```text
json      Machine-readable impact result.
md        Human-readable impact report.
canvas    Obsidian JSON Canvas for affected relations.
```

## links

List normalized links from one GSP id and its context.

```bash
gsp links <id> [--root .] [--depth -1] [--format json|md] [--out links.json]
```

The tool resolves link kind and status:

```text
kind: url | file | folder | missing | unknown
status: ok | missing | invalid | unchecked
```

## message

Validate GSP agent communication messages.

```bash
gsp message validate <file> [--root .] [--out message-report.json]
```

Message files use YAML and reference GSP ids from the project.

## graph

Generate a relation graph.

```bash
gsp graph [id] [--root .] [--depth 3] [--format json|mermaid|md|canvas] [--out graph.json]
```

Formats:

```text
json      Machine-readable graph.
mermaid   Mermaid graph body.
md        Markdown file with Mermaid block.
canvas    Obsidian JSON Canvas file.
```

Graph display uses `title` when present and falls back to `id`.

## stage-check

Check minimum resolution for a stage.

```bash
gsp stage-check --stage implement [--root .] [--out stage-report.json]
```