> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

# Crewship manifest reference

The manifest is Crewship's declarative deployment surface: a YAML (or JSON, since JSON is YAML 1.2) file that captures every user-creatable entity as data. One `crewship apply --file foo.yaml` (or `crewship apply --dir ./manifests/`) converges the workspace to match. `crewship export workspace` round-trips back.

This page is the index. Per-kind details live in `docs/manifest/<kind>.md`.

## Why manifests

* **GitOps for Crewship.** Commit a manifest to git, deploy to dev / staging / prod from CI. No clickops drift.
* **Sharing without screenshots.** Send a workspace YAML to a teammate; they apply it and have an identical setup.
* **Reproducible disasters.** Backups + export = a complete restore path.
* **Less surface for human error.** YAML linting + manifest validation catch typos before they reach the server.

## Kinds at a glance

Every document has the shape:

```yaml theme={null}
apiVersion: crewship/v1
kind: <Kind>
metadata:
  name: <human-readable>
  slug: <kebab-case, unique within workspace>
spec:
  ...kind-specific...
```

### Workspace structure

| Kind                                   | What it is                                                                         | Lifecycle | Doc                                     |
| -------------------------------------- | ---------------------------------------------------------------------------------- | --------- | --------------------------------------- |
| [`Workspace`](/manifest/workspace)     | Top-level bundle: credentials + skills + crews                                     | full CRUD | [workspace.md](/manifest/workspace)     |
| [`Crew`](/manifest/crew)               | One crew: agents + sidecars + MCP servers + credentials                            | full CRUD | [crew.md](/manifest/crew)               |
| [`Agent`](/manifest/agent)             | Single agent within a crew (used inline under `Crew.spec.agents` or standalone)    | full CRUD | [agent.md](/manifest/agent)             |
| [`Skill`](/manifest/skill)             | Skill registry entry (used inline under `Workspace.spec.skills`)                   | full CRUD | [skill.md](/manifest/skill)             |
| [`Integration`](/manifest/integration) | MCP server integration (workspace-, crew-, or agent-scoped)                        | full CRUD | [integration.md](/manifest/integration) |
| [`Issue`](/manifest/issue)             | Issue tracker row (rarely declared standalone — typically managed via the API/CLI) | full CRUD | [issue.md](/manifest/issue)             |
| [`Project`](/manifest/project)         | Container for missions and milestones                                              | full CRUD | [project.md](/manifest/project)         |
| [`Label`](/manifest/label)             | Tag for issues and missions                                                        | full CRUD | [label.md](/manifest/label)             |
| [`Milestone`](/manifest/milestone)     | Time-boxed project goal                                                            | full CRUD | [milestone.md](/manifest/milestone)     |

### Workflow + automation

| Kind                                              | What it is                                       | Lifecycle | Doc                                                  |
| ------------------------------------------------- | ------------------------------------------------ | --------- | ---------------------------------------------------- |
| [`Routine`](/manifest/routine)                    | Workflow DSL (steps + schedules + webhook)       | full CRUD | [routine.md](/manifest/routine)                      |
| [`RecurringIssue`](/manifest/recurring_issue)     | Issue template + cron → periodic issue creation  | full CRUD | [recurring\_issue.md](/manifest/recurring_issue)     |
| [`TriageRule`](/manifest/triage_rule)             | Match + actions for auto-routing incoming issues | full CRUD | [triage\_rule.md](/manifest/triage_rule)             |
| [`WorkflowTemplate`](/manifest/workflow_template) | Custom issue status flow (Kanban-style stages)   | full CRUD | [workflow\_template.md](/manifest/workflow_template) |

### Views + ops

| Kind                                | What it is                                                       | Lifecycle           | Doc                                    |
| ----------------------------------- | ---------------------------------------------------------------- | ------------------- | -------------------------------------- |
| [`SavedView`](/manifest/saved_view) | Shared filtered list (issues / missions / runs)                  | full CRUD           | [saved\_view.md](/manifest/saved_view) |
| [`Page`](/manifest/page)            | Dashboard of typed, permissioned panels that producers push into | full CRUD           | [page.md](/manifest/page)              |
| [`Hook`](/manifest/hook)            | Toggle for code-registered lifecycle hooks                       | enable/disable only | [hook.md](/manifest/hook)              |

### Catalog references (install / deploy)

| Kind                                      | What it is                                     | Lifecycle              | Doc                                          |
| ----------------------------------------- | ---------------------------------------------- | ---------------------- | -------------------------------------------- |
| [`Recipe`](/manifest/recipe)              | Install a recipe from the server catalog       | install only           | [recipe.md](/manifest/recipe)                |
| [`CrewTemplate`](/manifest/crew_template) | Deploy a crew from a template blueprint        | deploy only (one-shot) | [crew\_template.md](/manifest/crew_template) |
| [`Connector`](/manifest/connector)        | Install an OAuth connector (Linear, GitHub, …) | install only           | [connector.md](/manifest/connector)          |

### Instance / org config

| Kind                                            | What it is                                                               | Lifecycle | Doc                                                |
| ----------------------------------------------- | ------------------------------------------------------------------------ | --------- | -------------------------------------------------- |
| [`FeatureFlag`](/manifest/feature_flag)         | Toggle experimental features (instance-default + per-workspace override) | full CRUD | [feature\_flag.md](/manifest/feature_flag)         |
| [`InstanceSetting`](/manifest/instance_setting) | Key/value config (SMTP, branding, …) — admin-only                        | full CRUD | [instance\_setting.md](/manifest/instance_setting) |

## Foreign-key references

Cross-kind references always use the **slug** of the referenced entity. The apply pipeline resolves slug → id after the dependency is created.

```yaml theme={null}
# Milestone references Project by slug
kind: Milestone
spec:
  project_slug: q2-roadmap   # ← resolves to projects.id

# RecurringIssue references Project + Labels + Crew by slug
kind: RecurringIssue
spec:
  template:
    project_slug: q2-roadmap
    labels: [recurring, status]
    crew_slug: my-crew
```

## Apply order (topological)

`crewship apply` runs kinds in this order so dependencies are created before dependents:

1. Workspace credentials + skills (existing)
2. Crews + agents (existing)
3. **Projects, Labels** (no deps)
4. **Milestones** (deps: Projects)
5. **WorkflowTemplates**
6. **FeatureFlags, InstanceSettings**
7. **Recipes, CrewTemplates, Connectors** (catalog installs)
8. **Routines** (deps: Crews, Agents)
9. **Schedules + Webhooks** (nested in Routines)
10. **RecurringIssues** (deps: Projects, Labels, Crews)
11. **TriageRules** (deps: Projects, Labels, Crews)
12. **SavedViews** (deps: Labels, Projects)
13. **Pages** (deps: Crews, Agents, Routines)
14. **Hooks** (toggles only)

## Apply modes

```bash theme={null}
crewship apply --file foo.yaml                # ApplyUpsert (default): create/update/delete to match
crewship apply --file foo.yaml --strict       # Fail if any slug already exists
crewship apply --file foo.yaml --replace --yes # Destructive: delete existing, recreate fresh
crewship apply --file foo.yaml --dry-run      # Plan only — no mutations
crewship apply --dir ./manifests/             # Walk a directory; apply every YAML/JSON in topo order
```

## Round-trip via export

```bash theme={null}
crewship export workspace                     # everything in the workspace (multi-doc YAML)
crewship export workspace --output ws.yaml    # write to a file instead of stdout
crewship export crew uo-outlands              # the crew + everything labelled `crew: uo-outlands`
crewship export crew uo-outlands --no-skill-bodies  # slug-only skill references
```

## CLI per-kind admin commands

Every kind also has a per-entity CLI surface for one-off operations (no manifest needed):

| Kind             | Command                                                                     |
| ---------------- | --------------------------------------------------------------------------- |
| Project          | `crewship project list/get/create/update/delete`                            |
| Label            | `crewship label list/create/update/delete`                                  |
| Milestone        | `crewship project milestone list/create/update/delete`                      |
| Routine          | `crewship routine list/save/run/schedules/webhooks/...` (alias: `pipeline`) |
| RecurringIssue   | `crewship recurring list/delete`                                            |
| TriageRule       | `crewship triage list/process`                                              |
| SavedView        | `crewship saved-view list/delete`                                           |
| Page             | `crewship page list/get/create/update/delete/set/grant/revoke`              |
| WorkflowTemplate | `crewship workflow list/get/create/delete`                                  |
| FeatureFlag      | `crewship feature-flag list/enable/disable/inherit`                         |
| InstanceSetting  | `crewship instance settings list/get/set/delete`                            |
| Hook             | `crewship hooks list/enable/disable`                                        |
| Recipe           | *(manifest-only — install via `crewship apply`)*                            |
| CrewTemplate     | `crewship template list/get/deploy`                                         |
| Connector        | *(manifest-only — install via `crewship apply`)*                            |

## Examples

* [examples/manifests/full-complete.yaml](https://github.com/crewship-ai/crewship/blob/main/examples/manifests/full-complete.yaml) — one document per kind in one file
* [examples/manifests/full-team.workspace.yaml](https://github.com/crewship-ai/crewship/blob/main/examples/manifests/full-team.workspace.yaml) — multi-crew workspace (legacy shape)
* [examples/manifests/code-review.crew.yaml](https://github.com/crewship-ai/crewship/blob/main/examples/manifests/code-review.crew.yaml) — single-crew (legacy shape)

## What's NOT in the manifest (and why)

Some entities are deliberately out of scope:

| Entity                                             | Why not                                                                                         |   |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------- | - |
| `missions`, `agent_runs`, `pipeline_runs`, `chats` | Runtime instances, not declarative state                                                        |   |
| `audit_logs`, `notifications`, `cost_ledger`       | Telemetry, not config                                                                           |   |
| `workspace_members`, `crew_members`                | IAM lives in SSO / UI / CSV import, not YAML                                                    |   |
| `sessions`, `cli_pairings`, `oauth_states`         | Ephemeral auth state                                                                            |   |
| `backup_catalog`, `scheduled_jobs`                 | System runtime                                                                                  |   |
| `keeper_requests`, `approvals_queue`               | Runtime instances of policies (policies themselves may land in a future `kind: ApprovalPolicy`) |   |

## See also

* `SPEC-2-manifest-complete.md` — implementation contract / full schema (internal spec, in-repo)
* PRD: API — internal product spec (in-repo)
* PRD: ORCHESTRATION — internal product spec (in-repo)