# Project Manifest Reference

Each project context pack is described by an `aiw.project.json` file at the root of the context pack.

The manifest defines project identity, storage paths, connectors, code locations, and AI client preferences. Paths are relative to the context pack unless explicitly absolute.

## Minimal Manifest

```json
{
  "schema": "aiworkspace.project.v1",
  "id": "my-project",
  "display_name": "My Project",
  "knowledge_dir": "knowledge",
  "inbox_dir": "inbox"
}
```

## Full Example

```json
{
  "schema": "aiworkspace.project.v1",
  "id": "client-mobile",
  "display_name": "Client Mobile",
  "description": "Project context pack for a mobile application team.",
  "knowledge_dir": "knowledge",
  "inbox_dir": "inbox",
  "connectors_dir": "connectors",
  "prompts_dir": "prompts",
  "agents_dir": "agents",
  "connectors": {
    "mattermost": {
      "enabled": true,
      "config": "connectors/mattermost.json"
    },
    "photos": {
      "enabled": true,
      "config": "connectors/photos.json"
    }
  },
  "code_locations": [
    {
      "name": "Development machine",
      "availability": "remote-machine"
    }
  ],
  "ai_clients": {
    "opencode": {
      "enabled": true
    },
    "copilot": {
      "enabled": true
    }
  }
}
```

## Fields

| Field | Required | Description |
|---|---:|---|
| `schema` | yes | Manifest schema version. Current target: `aiworkspace.project.v1`. |
| `id` | yes | Stable lowercase project id used by CLI and MCP. |
| `display_name` | yes | Human-friendly project name. |
| `description` | no | Short project description. |
| `knowledge_dir` | yes | Canonical Markdown memory directory. |
| `inbox_dir` | yes | Raw evidence directory. |
| `connectors_dir` | no | Directory for connector configs. Defaults to `connectors`. |
| `prompts_dir` | no | Directory for project prompts. Defaults to `prompts`. |
| `agents_dir` | no | Directory for project agent config. Defaults to `agents`. |
| `connectors` | no | Connector registry for this project. |
| `code_locations` | no | Local or remote code locations associated with this project. |
| `ai_clients` | no | AI client integration preferences. |

## Code Locations

Code may be local, remote, or unavailable on the current machine.

```json
{
  "name": "iOS App",
  "path": "/Users/dev/Developer/app-ios",
  "role": "consumer-app",
  "availability": "local"
}
```

Supported target availability values:

- `local`
- `remote-machine`
- `not-configured`
- `unknown`

## Connector Configs

Connector definitions should describe source behavior without storing secrets.

Example `connectors/mattermost.json`:

```json
{
  "schema": "aiworkspace.connector.mattermost.v1",
  "enabled": true,
  "context_channels": [
    "team-standup",
    "team-code-review"
  ],
  "secret_refs": {
    "session": "keychain:aiworkspace/mattermost/session"
  }
}
```

## Validation Rules

A production-ready manifest validator should check:

- required fields exist;
- project id is stable and path-safe;
- configured directories exist or can be created;
- connector config files exist when enabled;
- secrets are referenced, not embedded;
- code locations are explicit about local vs remote availability.