# aachat documentation

> aachat is the Agentic Company Builder. Entrust AI agents with larger pieces of company work, from objectives to results. Build and improve your Projects, Workflows, and agents as code, so your company can take on more ambitious work.

# aachat Official Documentation

> An introduction to aachat and a guide to its concepts, setup, and features.

# aachat Official Documentation

**aachat is the Agentic Company Builder.**

**Entrust AI with larger pieces of company work.**
Build and improve your projects, workflows, and agents working as employees, just like code.

Start with [Concepts](/en/docs/concepts) for the product structure, [Setup](/en/docs/setup) to begin using it,
or [Trust Boundary](/en/docs/trust-boundary) for execution and data handling.

## Start and understand

| Page | Contents |
|---|---|
| [Documentation](/en/docs/index) | Choose an article or a machine-readable entry point |
| [Concepts](/en/docs/concepts) | Teams, Projects, Agents, work, and results |
| [Setup](/en/docs/setup) | Prerequisites, authentication, and your first request |
| [macOS Desktop](/en/docs/desktop) | Install, start, and update the Mac launcher |
| [Trust Boundary](/en/docs/trust-boundary) | Local runtime, provider, browser, and server data |

## Organize and carry out work

| Page | Contents |
|---|---|
| [Teams](/en/docs/teams) | Visibility, membership, roles, and repository access |
| [Projects](/en/docs/projects) | Lead, Asks, child work, completion, and cleanup |
| [Agents](/en/docs/agents) | Repository, owner, capabilities, and Runtime selection |
| [Sessions](/en/docs/sessions) | Start, continue, delegate, and inspect results |
| [Workflows](/en/docs/workflows) | Create a Draft, publish, run, and recover Steps |
| [Workflow reference](/en/docs/workflow-reference) | Bundle, typed schemas, dependencies, and child definitions |
| [Triggers](/en/docs/triggers) | Time and document conditions for future work |
| [Permissions](/en/docs/permissions) | Choose who can read, change, approve, or share |

## Keep and share results

| Page | Contents |
|---|---|
| [Shared Documents](/en/docs/shared-documents) | Save documents, use WikiLinks, and resolve sync conflicts |
| [Markdown blocks](/en/docs/markdown-blocks) | Markdown, diagrams, structured blocks, and sharing differences |
| [Project Database](/en/docs/database) | Migrations, SQL, read-only tables, and safe recovery |
| [Media](/en/docs/media) | Publish finished images, videos, and PDFs |
| [HTML](/en/docs/html) | Static browser deliverables and sharing |
| [Sharing](/en/docs/sharing) | Audience, live read access, expiry, and revocation |
| [Code Delivery](/en/docs/code-delivery) | Native delivery, exact HEAD, receipts, and local state |

## Grow company knowledge and capabilities

| Page | Contents |
|---|---|
| [Company](/en/docs/company) | Concepts, Entities, and the company map |
| [Concept Registry](/en/docs/concept-registry) | Proposals, revisions, sources, and human review |
| [Meetings](/en/docs/meetings) | Save and revisit Team meeting notes |
| [Skills](/en/docs/skills) | Sources, installation, usage, and improvement history |
| [Discover](/en/docs/discover) | Find, clone, publish, sync, and unpublish capabilities |
| [Templates](/en/docs/templates) | Document-kind, Project, and client-entry templates |

## Connect, operate, and recover

| Page | Contents |
|---|---|
| [Environment](/en/docs/environment) | Dependencies and local secret-name approvals |
| [Connected Repo](/en/docs/connected-repo) | Connect external coding agents and welcome clients |
| [External Session Runs](/en/docs/external-session-runs) | Start from CI or webhooks with scoped credentials |
| [Developer API](/en/docs/developer-api) | Entry points, authentication, requests, and retries |
| [WebUI](/en/docs/webui) | Screen navigation, search, notifications, and attachments |
| [CLI](/en/docs/cli) | Public and Session command syntax and output |
| [Limits](/en/docs/limits) | Bytes, dimensions, durations, SQL bounds, and paging |
| [Troubleshooting](/en/docs/troubleshooting) | Find the recovery path by symptom |
| [Glossary](/en/docs/glossary) | Definitions linked to their responsibility pages |

## Read with an AI or as Markdown

Use [llms.txt](/llms.txt) to discover the English articles and their descriptions; [llms-full.txt](/llms-full.txt) combines the English titles, descriptions, and full bodies. These endpoints are not Japanese translations. For Japanese or an individual English article, append `.md` to its localized URL, such as [this English guide in Markdown](/en/docs/index.md) or [the Japanese guide in Markdown](/ja/docs/index.md). Requesting an article with `Accept: text/markdown` also returns Markdown; ordinary browser links above open HTML.

The [outside-agent operating contract](/orchestration-skill.md) is the installable five-file skill for starting, operating, continuing and improving aachat work from Codex or Claude Code, including without a connected repository. The [support contract](/aachat-support.md) is the diagnostic procedure loaded by `aachat support`. Neither is a general article or a Session's generated runtime instructions. Use [Connected Repo](/en/docs/connected-repo) for connection steps and [Troubleshooting](/en/docs/troubleshooting) for symptoms, then read only the contract needed for the work.


---

# Concepts — The Building Blocks of the aachat World

> How Teams, Projects, Agents, and Sessions relate, and where company context, deliverables, and capabilities live.

# Concepts — The Building Blocks of the aachat World

aachat aims to make it possible to entrust AI with difficult work that requires company context and judgment.
You can define how work is carried out in Projects and Workflows, and develop each agent’s knowledge and skills in its repository.

## Agentic Company

This is the kind of company aachat aims to enable:

An Agentic Company is a company where AI agents understand the company, share roles with humans,
carry company work from objectives through to verified results, and reuse capabilities gained from that work in future work.

## Central concepts and relationships

| Concept | Role | Details |
|---|---|---|
| Team | The unit that humans belong to and share company context within | [Teams](/en/docs/teams) |
| Project | A place for work within a Team, where humans and agents share conversations, decisions, and deliverables | [Projects](/en/docs/projects) |
| Agent | A worker owned by a human, with its role, knowledge, and skills held in a repository | [Agents](/en/docs/agents) |
| Session | One instance of an agent running to carry out work | [Sessions](/en/docs/sessions) |
| Turn | One instruction being processed within a Session | [Glossary](/en/docs/glossary) |

Agents do not belong to Teams; they participate in Projects.
One agent can work in multiple Sessions, and the agent remains after a Session ends.
Agents execute on a connected machine; the aachat server shares and stores Project documents, conversations, and execution records.
See [Trust Boundary](/en/docs/trust-boundary) for storage and communication details.

## Where context and deliverables live

| Place | What it holds | Details |
|---|---|---|
| Team | Concepts for decision criteria and Entities for the things that make up the company | [Company](/en/docs/company), [Concept Registry](/en/docs/concept-registry) |
| Project Timeline | Messages and Asks that request decisions or information from humans | [Projects](/en/docs/projects) |
| Shared Documents | Shared specifications, deliverables, and supporting material for decisions | [Shared Documents](/en/docs/shared-documents) |
| Session Timeline | That Session's conversation and tool execution history | [Sessions](/en/docs/sessions) |
| Agent repository | The agent's role, knowledge, memory, and reusable capabilities | [Agents](/en/docs/agents), [Skills](/en/docs/skills) |

[HTML](/en/docs/html) holds browser deliverables, and [Media](/en/docs/media) holds images, videos, and other media.
A shared document is not necessarily verified or approved.

## Improve company structures and capabilities

A request arrives in a Project, and an agent carries it out in a Session.
Shared deliverables and decisions remain in the Project; changes to the agent's knowledge and capabilities remain in its repository.
Later Sessions can refer to them and test improved ways of working and capabilities in actual work.

**Company as Code** is a way for humans and agents to read, change, verify, and improve company structures such as Projects and Workflows.
**Agent as Code** is a way to build and develop the knowledge, judgment criteria, and skills of agents working as employees in repositories.
See [Projects](/en/docs/projects) for objectives and ways of working, [Workflows](/en/docs/workflows) for editing and publishing execution definitions, and [Agents](/en/docs/agents) and [Skills](/en/docs/skills) for changing capabilities and applying them in future Sessions.

See [Sessions](/en/docs/sessions) for delegation and [WebUI](/en/docs/webui) for where to find each screen.

## Repeatable work and its results

A [Workflow](/en/docs/workflows) defines typed Steps and dependencies. Edit its Draft, publish an immutable Revision, and start a Run with fixed input. An Attempt is one execution of a Step. A human Decision pauses the dependency flow for an Ask; ordinary Session delegation is useful when the next instruction is decided as work proceeds. A [Trigger](/en/docs/triggers) starts a fresh Session or published Workflow on a time schedule or document match; a scheduled follow-up instead adds work to an existing Session.

[Project Database](/en/docs/database) holds structured rows, while [Meetings](/en/docs/meetings) preserve Team meeting notes separately from Project documents. [Code Delivery](/en/docs/code-delivery) records successful native pushes and PR creation for the workspace and Agent repositories. A stopped Session, a delivery receipt, and a reviewed result answer different questions: inspect the actual document, data, or code before accepting the outcome.


---

# Trust Boundary — What Is Local, What Is Server

> This page is the single source for execution, stored data, secrets, transport, and outage boundaries across the local agent runtime, viewer browsers, and the aachat server.

# Trust Boundary — What Is Local, What Is Server

Agent processes and file operations run on the execution machine; the aachat server shares and stores Project documents, conversations, and execution records. That does not mean "fully local" or "the server stores metadata only." Use this page as the source of truth for security, data location, transport, and outage behavior.

There are three execution and storage layers.

| Layer | Execution and storage |
|---|---|
| **local agent runtime** | Claude Code / Codex and file operations, raw inference traffic to the LLM provider, session environment secrets, workspace repo |
| **Project HTML viewer browser** | JavaScript authored under project `html/` executes in each member or public-share viewer's browser |
| **aachat server** | Project messages and execution records, Shared Documents, session transcripts, Project Media / HTML, credentials and access control |

## Local agent runtime

- The coding-agent process and workspace file / command operations run on the owner's machine. The local runtime connects to the LLM provider, where provider inference is performed. Permissions follow Claude Code / Codex, with allow, deny, and interruption available from the WebUI Workspace panel
- Raw inference traffic to the LLM provider originates from the local runtime. aachat does not run the LLM or meter and bill its tokens
- Ordinary workspace and agent repo contents are not uploaded to the aachat server to run a session. Explicit project projections under `docs/`, `media/`, and `html/` are the exception
- Session environment secret values live in the owner's `~/aachat/.run/.env` or Infisical CLI. Only names approved per agent in `~/aachat/.state/env.toml` enter a session ([Environment](/en/docs/environment))
- The agent repo itself lives on GitHub and in a local clone, not on the aachat server. Session stderr logs are also local under `~/aachat/.run/logs/`

## What is sent to and stored on the aachat server

The local runtime does not use WebSocket alone. WebSocket carries real-time runtime control and delivery; HTTPS APIs handle persistence and project operations.

- project messages, Project Timeline, Asks, search indexes, membership, and roles
- **Shared Documents.** The server is canonical; local `aachat/projects/` is a projection synced while `aachat up` runs
- **Session records and transcripts.** Session events persisted on the server include user and agent messages, display representations of reasoning and tool calls, and execution configuration and usage. This does not mean raw LLM-provider traffic passes through the server
- Project Media; Project HTML source and serving snapshots
- the agent catalog, skills / Skill Ledger, templates, and the Company model (Concept / Entity)
- External Session Run credential configuration and token hashes. The token value is shown only when issued ([External Session Runs](/en/docs/external-session-runs))

Connecting an ordinary development repo with `aachat init` does not store that entire repo on the server. Do not place confidential code you do not want on the server under project `html/`, `docs/`, or `media/`.

New permanent Session history retains tool inputs, identifiers, and status, but does not store tool output bodies, raw output, or output-derived diffs. Size limits can also omit inputs; complete input text is not guaranteed. Receiving output for live display is separate from storing it in permanent history. Conversation text and artifacts such as Shared Documents remain stored; this policy does not guarantee deletion of all older history or other storage. See [preserving results for later review](/en/docs/sessions).

## Secrets and external credentials

| Type | Storage | Recipient |
|---|---|---|
| **session environment secret** | Owner's local provider (`.env` / Infisical) | Local agent sessions whose name is approved in `env.toml` |

The platform contract avoids intentionally printing secret values, but it cannot guarantee that local agent code receiving a value will never transmit it. Minimize approved secrets and review the code and authority that receive them.

The Bearer API key for an External Session Run is separate again. Its value is shown only when issued; the server stores a token hash and the fixed agent / mode / repo configuration. It is not injected into a workload. It authorizes an external system to start a new session ([External Session Runs](/en/docs/external-session-runs)).

## Project HTML viewer browser

Project HTML source and serving snapshots are stored on the server, but authored JavaScript executes in the browser of each member or public-share viewer who opens it. Delivery security headers use CSP to block framing, objects, base-URL changes, ordinary forms, and Workers, while Permissions-Policy disables device APIs. The CSP does not define `script-src` or `connect-src`; scripts can therefore run and initiate network requests under browser rules. Review generated HTML before opening or sharing it, and do not embed secrets or privileged credentials ([HTML](/en/docs/html)).

## Authentication and writes

- CLI authentication uses the local `gh` token to issue a short-lived JWT cached at `~/aachat/.run/tokens/user.jwt`. The GitHub token itself is not stored in the project
- `aachat init` writes only inside the connected repo and `~/aachat/.state/repo-connections/`. Writes outside the repo and through symlinks are rejected
- Each member using a team default workspace repo needs their own GitHub credential, repo read/write access, and organization SSO authorization where required. aachat does not grant repository access ([Teams](/en/docs/teams))

## During a server outage

An already-running coding agent can continue local file operations and provider requests during an aachat server outage, provided its runtime, network, and LLM provider remain available. HTTPS API / WebSocket-dependent transcript persistence, messages, Shared Documents sync, new session starts, follow-ups, and handoffs stop. Project projections re-sync after recovery while `aachat up` is running.

## Guarantees not implemented or evidenced

- aachat has no mechanism that restricts a local agent runtime's network destinations. `networking.type` in `environment.yaml` is declaration-only. Use the Claude Code / Codex sandbox and permissions when restrictions are required
- Current public documentation does not evidence SSO / SCIM / SOC2 / immutable audit logs or a complete retention and deletion guarantee for server data. Do not promise them

## Quick answers

| Question | Answer |
|---|---|
| Where does the LLM run? | At the LLM provider reached by the local Claude Code / Codex runtime; the client process runs on the owner's machine |
| Does session conversation reach the server? | Yes. The transcript, display representations of reasoning/tool calls, and execution metadata are persisted over HTTPS. New permanent history does not store tool output |
| Is WebSocket the only transport? | No. WebSocket is for real-time control; HTTPS APIs persist and operate on projects |
| Are all secrets local? | Session environment secrets are local. External Session Run credentials are issued once and stored as hashes on the server |
| What is canonical for Shared Documents? | The server. Local `aachat/projects/` is a projection |
| Where does agent-written code run? | Session code is local; Project HTML JavaScript runs in each viewer's browser |
| Where are conversation and execution logs? | Transcript on the server via `session read`; stderr local via `session logs` |
| What stops in a server outage? | Persistence, sync, messages, and session coordination. Existing runtime file operations and provider requests can continue if those dependencies remain available |

## Structured data and public access

[Project Database](/en/docs/database) rows live in a server-managed Cloudflare D1 database for each ordinary Project. Server-side Postgres holds its metadata and schema cache; `db/schema.sql` is a read-only local projection and `db/migrations/` contains migration sources. This is another explicit Project data surface: local migration sync does not execute SQL, and editing workspace code does not automatically upload it into the database. A running covered Session uses role-checked server operations. The WebUI table browser is read-only.

New database operations stop when the Project is no longer active. Accepted work can finish, and Project deletion waits for query leases, migration reconciliation, and physical database deletion. A deleted local file is neither a rollback nor proof of server erasure.

[Public shares](/en/docs/sharing) deliberately cross the membership boundary. Anyone with a valid Markdown token can read its scope without logging in. A document token reads the current document and authorized media dependencies; an Admin-created context token can read Project records, documents, and Project session transcripts, including later content. These are live reads, not immutable exports. UI links last 7 days; authorized creators/Admins can revoke them as described in Sharing. Copies already downloaded cannot be recalled.

Media `/m/<uuid>` URLs still require membership unless access is delivered through an authorized share dependency. Share HTML exposes a built static surface and executes its JavaScript in the recipient's browser; it does not grant the author's server credentials or database access. Before publishing, inspect both content and dependencies and choose the smallest suitable sharing scope.


---

# Setup — From Install to the First Request

> The exact steps from prerequisites, CLI install and auth, obtaining an agent, starting `aachat up`, through the first request in a project. This page also covers headless / CI operating conditions and the roles of status / doctor / update.

# Setup — From Install to the First Request

Follow these steps from sign-in to the first request in a Project. Check the result at each stage so you can identify what needs attention if setup stops. For app-guided Mac startup, use [Desktop](/en/docs/desktop), then return here to obtain an Agent and create your first Project.

## Start from an external agent

Paste this prompt into Codex or Claude Code to get help with setup through handing off your first task.

```text
Read https://aachat.io/orchestration-skill.md,
set up aachat, and help me hand off my first task.
```

Your agent follows the linked instructions to save the skill and install the CLI with the official installer. Use the same entry point if the CLI is already installed. You will be prompted for steps that need you, such as signing in. A connected repository is optional. To set up manually, follow the steps below.

## Prerequisites

| Prerequisite | Condition |
|---|---|
| OS | One of macOS / Linux / WSL2 (Ubuntu) |
| GitHub account | Used for sign-in and storing agent repos |
| GitHub CLI (`gh`) | Installed and `gh auth login` completed |
| Coding agent | For the Claude runtime, Claude Code (`claude`) is installed; for Codex, the Codex CLI is installed and signed in |
| Node.js | 22 or later (`node` / `npm`). Used to start `aachat up` |

If anything is not installed, complete it first via each official procedure. Even if Claude Code was installed via npm, confirm that `node --version` is 22 or later.

## Sign in

Open aachat.io in a browser and sign in with GitHub. On completion, a personal team (slug `~<login>`) is created automatically and Home opens.

Check: the Home screen opens and the personal team appears in the team menu.

## Install the CLI

```bash
curl -fsSL https://aachat.io/install | sh
```

The `aachat` binary and related binaries such as `chat` (used to run agents) are installed into `~/.cargo/bin`, and PATH is appended.

```bash
aachat --version
```

If a version is printed, the install is complete. On `command not found`, open a new terminal. The installer appends PATH to your shell config file, so terminals that were already open may not pick it up.

## Authenticate

```bash
aachat auth login
```

Issues a short-lived JWT from the local `gh` token and caches it at `~/aachat/.run/tokens/user.jwt`. If `gh` is already authenticated, no interaction occurs.

Check: `✓ Cached aachat JWT for <name>` is displayed.

## Diagnose the environment

```bash
aachat doctor
```

Diagnoses, in one pass, the GitHub CLI and its token permissions, Claude Code, connectivity to the aachat API, and login state (User JWT). For any `✗` line, resolve it with the steps shown directly below it (the command after `Run:`) and re-run.

The coding-agent check in `aachat doctor` currently diagnoses Claude Code; it does not validate Codex sign-in. For a Codex runtime, confirm sign-in with the Codex CLI separately, then verify startup in the `aachat up` Launch Report and the first session.

Check: resolve the failures relevant to your chosen runtime. A missing Claude check does not verify or disprove Codex readiness; check Codex separately as described above.

## Obtain an agent

There are 3 paths. Whichever path you take, what gets created is the same — a single GitHub repo that is the agent's substance, and a registration on the team that references it (the agent repo structure is in [agents](/en/docs/agents)).

| Path | Operation |
|---|---|
| Clone from Discover | In the WebUI, Discover → Agents, pick a public agent, and Clone. After GitHub authorization, the source repo's contents are copied as a private repo in your GitHub account, and an agent referencing that repo is automatically registered to the team |
| Create via CLI | `aachat agent create <name>` |
| Create via WebUI | Create from Agents in the sidebar |

You may leave the GitHub repo field unspecified when creating an Agent. Its first `aachat up` then creates a private repo from the template. If you specify an existing repo, aachat uses that repo; it does not promise to scaffold an empty one.

Check: your agent appears under Agents in the sidebar.

## Start the runtime — `aachat up`

```bash
aachat up
```

Starts the runtimes of every agent you own, together in a single resident process. Real-time control uses WebSocket; transcript persistence and project operations use HTTPS APIs (the full boundary is in [trust-boundary](/en/docs/trust-boundary)). Agents can receive requests only while this process is running, so keep the terminal open. `Ctrl+C` stops all agents.

`aachat up` checks for updates at startup, and if a new binary exists, it self-updates and re-execs with the updated binary. This is a startup check; it does not continuously replace a running process when a new release appears. Use `aachat update` for an explicit CLI update and plan runtime restarts around active work.

Check: `● <agent-name> ready` appears in the terminal, and the agent shows as online in the WebUI's Agents.

### Runtime-specific prerequisites for Claude / Codex

- **Claude**: `claude --version` works and Claude Code is authenticated. Hooks / MCP / plugins / commands / custom allow-deny settings from the team workspace repo are inherited into the session and merged with aachat's required permissions
- **Codex**: install and sign in with the Codex CLI before switching the agent runtime to `codex-acp`. aachat prepares a pinned adapter; it does not create the user's Codex credentials

## Create a project and make a request

Sign in to the team and check that an agent you own is online. For your first Project, start without a parent.

1. Open **Projects → New Project** in the WebUI.
2. Enter a **Name** of 2–30 lowercase letters, numbers, or hyphens. Do not use `stream`, `dm`, or `repo`.
3. Select an agent you own as **Lead**. In **Brief**, describe the goal, background, expected deliverables, and constraints. The optional description does not replace the Brief.
4. Submit **Create** once. “Project created; setup session accepted” means the Project and its setup Session were accepted. You do not need to repeat the setup request from the composer.
5. Open the Lead's Session from the new Project's Work Panel. The agent prepares PROJECT.md and REPORT.md and may ask for missing details. After the setup Session ends, review both documents and request the next work you want the Lead to perform.

If Create is disabled, check Name, Lead, and Brief. If you cannot select a Lead or no response follows acceptance, use [Troubleshooting](/en/docs/troubleshooting) to check agent ownership, team, the ready line from `aachat up`, and runtime authentication.

Choosing a human Lead instead gives “Project created; human Lead notified”: this notifies a human and does not run an agent. Continue to the [Project guide](/en/docs/projects) for start conditions, answering Asks, and accepting results before Done. See the [Session guide](/en/docs/sessions) for additional requests.

## Connect a development repo (optional)

If you want external agents such as Cursor / Claude Code in your everyday development repo to participate in projects, run `aachat init` at that repo's root to connect it. Steps, placed files, and the write boundary are in [connected-repo](/en/docs/connected-repo).

## Operating in headless / CI environments

aachat can run in headless environments (CI, always-on servers). Two implemented facts support this.

- Authentication: if `gh` is authenticated, `aachat auth login` obtains a JWT non-interactively and caches it at `~/aachat/.run/tokens/user.jwt`
- Residency: `aachat up` runs as a resident process that requires no interaction

There is one more prerequisite. Agent execution happens on the coding agent (Claude Code / Codex) on that machine, so **the coding agent itself must be authenticated and runnable on the headless machine**. aachat's authentication (via `gh`) and the coding agent's authentication are separate; agents can work only when both are in place.

## Roles of the operational commands

| Command | Role |
|---|---|
| `aachat status` | Returns the state of repo connections, auth, daemon, mirror, docs, and the Launch Report as JSON. Use for status checks from scripts and agents |
| `aachat doctor` | Diagnoses environment health as human-readable text. Each `✗` item comes with resolution steps |
| `aachat update` | Updates aachat itself to the latest version. `aachat up` self-updates at startup; an already-running process does not become the new version just because a release exists |

## Choose the startup path and check its version

For an app-guided Mac setup, use [macOS Desktop](/en/docs/desktop). It checks prerequisites, signs in through the browser, installs its managed CLI, starts the local runtime, and opens the WebUI. The terminal procedure above remains the path for Linux, WSL2, and headless use.

```bash
aachat --version
chat --version
aachat status
```

Record versions before diagnosing a missing feature. Desktop has its own app version and updater; updating it and updating the CLI are different operations. A repository change or a guide update does not itself upgrade the binaries on your machine.

Use `aachat up --if-stopped` when you want to start only if no valid runtime is already running. It leaves an existing valid runtime alone and returns; if it starts a new one, that invocation stays resident. Plain `aachat up` can stop and replace an existing daemon, affecting active local work. Neither command promises an operating-system service or automatic restart after reboot. Keep the chosen runtime host running, and inspect status rather than repeatedly starting it.

## Keep the authentication paths separate

| Path | What it authorizes | What to check when it fails |
|---|---|---|
| WebUI GitHub sign-in | Your browser access to teams and Projects | Browser sign-in and current team/Project membership |
| CLI `aachat auth login` | aachat user access obtained from local `gh` authentication | `gh` login/permissions and `aachat doctor` |
| Desktop GitHub sign-in | The app's browser callback flow and local aachat login | Complete the app's fresh sign-in attempt; coding-runtime login is still separate |
| Claude / Codex login | Execution by the local coding runtime | Authenticate the selected runtime on the machine that runs the Agent |
| External Session Run API key | A fixed external-start credential | Expiry, rotation/revocation, owner and Project membership; see [External Session Run](/en/docs/external-session-runs) |
| Client entry | A temporary guest browser login for its dedicated Project | The originating browser and 7-day validity; see [Connected repo](/en/docs/connected-repo) |

Task-specific environment secrets are another layer, configured in [Environment](/en/docs/environment). Browser sign-in is not approval to inject a secret. Treat each credential's expiry or revocation at its own surface; do not assume signing out of one client revokes external-start keys or provider credentials.

## Related pages

- What is local and what is server, secret handling: [trust-boundary](/en/docs/trust-boundary)
- Agent repo structure and when changes take effect: [agents](/en/docs/agents)
- Session lifecycle and delegation: [Sessions](/en/docs/sessions)
- Connecting a development repo and external agent participation: [connected-repo](/en/docs/connected-repo)
- Diagnosis by symptom: [Troubleshooting](/en/docs/troubleshooting)


---

# agent — the entity is a GitHub repo, grown with git

> An agent's entity is a single GitHub repo. This page covers the repo layout (identity / memory / knowledge / skills / environment.yaml), when changes take effect, the relationship to the owner and the machine it runs on, and how agents are created and grown.

# agent — the entity is a GitHub repo, grown with git

The entity of an aachat agent is a single GitHub repo. 1 agent = 1 repo. Personality, memory, knowledge, and capabilities all exist as files in this repo and are managed as git versions. Agent names use the `{base}.{owner}` format (example: `researcher.kensaku`) — the owner's GitHub login is appended to the base name to form the full name.

When asked who an agent is, what it remembers, and what it can do, every answer is inside this repo. There is no magical internal state.

## agent repo layout

| Path | Role |
|---|---|
| `identity.md` | Personality, role, and behavioral guidelines. **Injected into the agent at session start** |
| `memory/` | The agent's own accumulated experience and judgments. Appended through work |
| `knowledge/` | Reference information needed for work (specs, style guides, etc.) |
| `.agents/skills/` | The normal source for agent skills, laid out as `<skill-name>/SKILL.md`. `.claude/skills/` is also read for Claude compatibility or existing assets |
| `environment.yaml` | Declares dependency packages and environment variable names. **Secret values cannot be written here** (details in [Environment](/en/docs/environment)) |

When a session starts, this repo is checked out as a worktree inside the session's workspace (`~/aachat/.run/workspaces/<full-name>--<sid8>/aachat/agents/<full-name>`). The local clone cache is at `~/aachat/.run/cache/`.

The agent repo is canonical for the agent's own learning, not for the deliverables of an individual project. The next session combines identity / memory / knowledge / skills from the agent repo with project-side context. When a task needs that context, it reads `PROJECT.md` first as the stable Project Contract / Context Router, then follows the curated Context Map to the Shared Documents it needs. It reads dynamic handoffs from a session transcript, short project message, or normal Shared Document. Keep settled deliverables and project-specific decisions on the project side; keep capabilities and rules of thumb that travel across projects in the agent repo ([Concepts](/en/docs/concepts)).

## When changes take effect — the most important fact

Changes to the agent repo are **made via git commit, and take effect from the next session after push**. This is a point where misunderstanding arises structurally, so convey it to users precisely.

- Editing files locally is not enough for changes to take effect. You must commit and push
- Even pushed changes **do not take effect in a running session**. They become effective from the next session that starts
- The same rule applies to all of `identity.md`, `memory/`, `knowledge/`, `.agents/skills/` (including the compatible `.claude/skills/` source), and `environment.yaml`

For the question "I changed the identity but the behavior didn't change," first have the user confirm two things: (1) did they push, and (2) did they start a new session after pushing.

The flip side of this rule is that **the repo is the source of truth for agent behavior**. Because what gets injected into a session comes from the pushed repo, local-only configuration drift never changes agent behavior. Every behavioral change is traceable as commit history and is subject to review and revert. When a team wants to govern agent behavior, this history serves directly as the audit record of changes.

## owner and the machine agents run on

- Only the **owner** can manage an agent (creation, repo changes, making it dormant). Team members other than the owner cannot manage the agent
- An agent **runs on the owner's machine**. The `aachat up` run by the owner starts the agent's runtime. If the owner's `aachat up` is not running, that agent's session will not start even when other members send requests
- The coding-agent process (such as Claude Code) and workspace file operations run on the owner's machine. That runtime connects to the LLM provider for inference; provider computation does not run on the owner's machine merely because the client does. **The server stores Project messages, Shared Documents, and session records; it does not run agent processes.** The full picture of this boundary is in [Trust Boundary](/en/docs/trust-boundary)

## Creating and acquiring an agent

There are three acquisition paths.

1. **Clone from Discover**: duplicate a published agent as your own agent. Cloning also automatically creates a DM project with that agent (`dm:<full-name>`)
2. **Create in the WebUI**: from Create Agent in the "Agents" sidebar. Names use alphanumerics, hyphens, and underscores. The GitHub repo field is optional (leaving it empty is the easy path). The runtime is `Claude` (default) or `Codex`
3. **CLI**: `aachat agent create`

When an agent is created without specifying a repo, **the first `aachat up` automatically creates a private repo `<login>/<agent-name>` from the template** and lays out the scaffold (`identity.md`, `memory/`, `knowledge/`, the normal `.agents/skills/` source, and the compatible `.claude/skills/` source) (this uses an already-configured `gh`; prerequisites are in [Setup](/en/docs/setup)). If `aachat up` is already running, the new agent is started automatically without a restart.

If you specify an existing repository instead, use one whose default branch is `main`. Managed Sessions record Agent-repository delivery against `main`; a repository with another default branch can start from that branch but will not satisfy the delivery receipt contract. Change its default branch before registering it, or leave the repo field empty and let aachat create the repository.

### Excluding an agent from launch (dormant)

Agents you will not use for the time being can be excluded from `aachat up` launch targets with the `dormant` flag.

```bash
aachat agent update <agent-name> --dormant     # exclude
aachat agent update <agent-name> --no-dormant  # restore (auto-starts if up is running)
```

Dormant agents are shown as `○ <name> dormant` at launch and recorded as `[dormant]` in the Launch Report (`~/aachat/.run/logs/up.log`).

### Deleting an agent

```bash
aachat agent delete <agent-name> --yes
```

Delete is irreversible and is not the same as dormant. It cancels active sessions and Session-scope Asks, deletes the owner's DM, removes every project membership, and tombstones the server agent. Local workspaces also become cleanup targets, so inspect uncommitted / unpushed work and any needed DM or session record first. Choose dormant instead when the agent may be used again.

## Agents grow

Agent growth means commits accumulating in the repo. Through work, `memory/`, `knowledge/`, and the normal `.agents/skills/` source build up and remain as git versions. Therefore all of the following are possible.

- **review**: check what was learned and when via commit history
- **revert**: roll back undesirable changes with git
- **clone**: duplicate a grown agent (and hand it to other users via Discover publication)

Editing in practice is ordinary git operations. The easy way is to directly edit the worktree checked out inside a running session's workspace.

```bash
# <sid8> is the first 8 characters of a session ID, found with aachat session list --agent <base-name>
cd ~/aachat/.run/workspaces/<full-name>--<sid8>/aachat/agents/<full-name>
# edit files
git add <reviewed-files>
git commit -m "<change description>"
git push origin HEAD:main
```

Cloning normally into a separate directory, editing, and pushing yields the same result. You can also have the agent grow itself by asking it to "append this to memory and push."

### The skill improvement loop

Create and update skills in the agent repo's normal source, `.agents/skills/<skill-name>/SKILL.md`. `.claude/skills/<skill-name>/SKILL.md` is also read for Claude compatibility or existing assets, but is not the normal authoring destination. If the same skill name exists in both, the `.agents/skills/` source takes precedence. The basic form of the improvement loop is to route it through the agent itself as a self-improvement request.

1. Ask the agent in a session to "turn this procedure into a skill so you can use it next time"
2. The agent writes the skill into its own repo (which the environment variable `AA_AGENT_DIR` points to inside a session), commits, and pushes
3. The skill is loaded **from the next session after the push** (there is no hot reload during a session)

Besides the agent's own skills, a session also gets aachat's platform skills (`aachat-*`) and the skills git-managed in the workspace repo projected into it. To avoid name collisions, give skills agent-specific names and do not use `aachat-*` names.

[skills](/en/docs/skills) is canonical for source precedence, Skill Ledger, and the feedback-to-improvement-session loop.

Helper commands:

- `aachat skills add <skill-name>` — places a skill into the normal `.agents/skills/` source of the current directory (changeable with `--target`) (requires Node.js because it uses `npx skills add --agent universal` internally)
- `aachat manage-agent` — an interactive entry point that walks through search, clone, identity editing, skill addition, and commit & push in one flow (requires the `claude` command)

## Default Runtime and per-Session selection — Claude Code / Codex

Each new Session runs on either `Claude` (Claude Code; `claude-acp`) or `Codex` (`codex-acp`). An agent's setting is only the initial default for future launch drafts; the selected Runtime is fixed independently for each Session. The default is Claude.

| Operation | Method |
|---|---|
| WebUI | Change the target agent's **Default runtime** on Home, or choose a Runtime in the Project composer |
| CLI | `aachat agent update <agent-name> --runtime codex-acp` (revert with `claude-acp`) |

- Changing the default affects only future launch drafts. It does not change running or existing Sessions and does not require restarting `aachat up`
- Choose a Runtime per Session in the WebUI composer or with `session run --runtime claude-acp|codex-acp`
- The selected Session Runtime determines workspace projections: Claude uses `.claude/` (`CLAUDE.md` and `.claude/skills/`), while Codex uses `AGENTS.md` and `.agents/skills/`. The agent repo's skills are loaded under either Runtime

## Relationship to Discover

- **Acquire**: clone a published agent from the Discover catalog to make it your own agent
- **Publish**: agents you have grown can be published to Discover. Use a reviewed public tree with `.aachat/public.yaml` and an explicit human-owner publication action; follow the procedure below

## Deliver an Agent change and verify it

For an edit made inside a managed Session, the Agent worktree can be detached. Push explicitly to the Agent repo's required `main` default branch, then record the successful operation with the Session CLI:

```bash
cd "$AA_AGENT_DIR"
git status --short
git add identity.md
git commit -m "Clarify research responsibilities"
git push origin HEAD:main
```

Stage the actual files you reviewed; `identity.md` is an example. The receipt records a successful push and does not perform one. A commit or a local edit alone is not delivery. Check the remote commit and begin a new Session to observe the change. If the receipt fails after a successful push, retry only the receipt from the same repository and HEAD; do not repeat the external operation just to obtain a receipt.

For a start failure, distinguish an offline owner runtime from an unavailable Runtime or unsupported configuration. Use the Runtime and options actually offered in the launch form. Arbitrary model/configuration values are not accepted merely because a coding CLI supports them. Correct runtime authentication or the offered configuration and launch a new Session; changing the Agent default does not repair an existing Session's fixed Runtime.

## Publish or return an improvement

[Discover](/en/docs/discover) gives the complete preparation, human publication, sync, and unpublish procedure. Publication needs `.aachat/public.yaml` and reviewed public files; making the working repository public or merely having `identity.md` is not a sufficient publication procedure. Private Agent development, public-copy updates, and catalog synchronization are separate steps.

A cloned Agent can draft an upstream improvement proposal for its human owner to review and send as a **GitHub Issue**. The proposal does not automatically update the source or your clone. Discover's separate reviewed code-improvement flow may create a PR; confirm which action the card will execute before approving it.

## Related pages

- The session lifecycle and workspace separation: [Sessions](/en/docs/sessions)
- The `environment.yaml` contract and how secrets are passed: [Environment](/en/docs/environment)
- What is local and what is server: [Trust Boundary](/en/docs/trust-boundary)
- Prerequisites and setup for `aachat up` and `gh`: [Setup](/en/docs/setup)
- Skill sources, precedence, and improvement history: [skills](/en/docs/skills)

## Choose an offered Runtime profile

Before launch, inspect the Runtime controls in the human launch form. A Session agent can discover current profiles with `chat project members <team>/<project> --runtime-profiles`. Select a Runtime and config IDs/values actually offered for that Agent; do not infer availability from a model name in an old transcript.

CLI overrides are typed: `--config <option-id>=id:<offered-value>` for an ID choice and `--config <option-id>=boolean:true` (or `false`) for a boolean. Repeat `--config` for separate options. `mode=id:plan` is only usable if the selected profile offers that exact option. Missing options use the profile defaults.

For a direct launch, omitting both Runtime and config can reuse the target Agent owner's saved launch preferences for that Agent in this Project; without saved preferences it resolves the Agent default. This applies to interactive human launches and direct Agent delegation. Explicit Runtime or config overrides do not reuse that preference set; config alone resolves against the Agent default Runtime. Workflow automation and external launches use their own accepted launch settings. Existing Sessions retain their accepted settings.

If launch rejects an unknown option, unsupported value, or unavailable profile, reread the offered profile and replace/remove only the invalid override. Check provider authentication and local Runtime availability when startup itself fails. Read the acceptance result and Session state before resending, so an accepted request is not duplicated. See [Sessions](/en/docs/sessions), [CLI](/en/docs/cli), and [Troubleshooting](/en/docs/troubleshooting).


---

# Skills — Sources of Truth and Improvement History

> This page explains where Agent, Team, and Platform skills come from, projection precedence, and how Skill Ledger turns usage and feedback into repo-backed improvements.

# Skills — Sources of Truth and Improvement History

A skill is a reusable capability or procedure for an agent. Its source of truth is `<skill-name>/SKILL.md` in a Git repository. This page is canonical for where skills live, which same-named skill is used, and how observed usage becomes an improvement. Read [agents](/en/docs/agents) first for the agent repo and the push-then-new-session rule.

## Three sources

| Source | Source of truth | Purpose |
|---|---|---|
| **Team** | Git-managed `.agents/skills/` or `.claude/skills/` in the session's workspace repo | Procedures shared by every agent working in that repo |
| **Agent** | The normal `.agents/skills/` source in the agent repo; `.claude/skills/` is also read for Claude compatibility or existing assets | Capabilities the agent carries across projects. `.agents/skills/` wins on duplicate names |
| **Platform** | Skills supplied to the session by aachat | Contracts for correctly operating aachat projects, documents, Asks, git, and related surfaces |

A top-level `skills/` directory is not loaded. Each skill needs a `SKILL.md`, stored as a normal UTF-8 file under git. Do not use symlinks or special files as skill sources.

## Projection and precedence

At session start, all three sources are projected into the runtime's skill discovery path. When the workspace repo and agent repo contain the same skill name, the **workspace / Team skill shadows the Agent skill**. This lets the repo-specific contract win in that session.

Platform skills are reserved contracts and cannot be overridden, but collision outcomes depend on the source.

- A workspace / Team skill with the same name as a Platform skill is a setup error
- An Agent skill with the same name is shadowed by the Platform skill; the session starts with the Platform version

Invalid paths and missing `SKILL.md` remain setup errors. Recovery and the source-specific collision cases are in [troubleshooting](/en/docs/troubleshooting).

The `aachat` skill that `aachat init` writes into a repo is not a Platform name, so it projects like any other workspace skill. Its own `SKILL.md` says it is not for use inside a session.

Because the repo is canonical, commit and push a skill change, then start a new session. There is no hot reload into a running session.

## Skill Ledger

**Skills** shows explicitly refreshed repository snapshots alongside observed usage and feedback. Starting a Session or opening the list does not rescan repositories. An Agent page shows Agent and Platform sources; Team and Project links select their own workspace repository and branch.

- **Refresh** checks one source at one GitHub commit and saves its `SKILL.md` files and Agent identity atomically. Failure or cancellation preserves the previous snapshot. Never fetched and confirmed empty are different states.
- Private sources require the signed-in person's GitHub authorization or the Team GitHub App installation matching that repository.
- Usage loads independently for the last 30 days. These are saved tool observations, not a complete usage rate. Missing observations, unavailable observations, and observed zero are distinct.
- Detail shows the saved source, branch, commit, and text. Files loads only the directory opened or file selected. Legacy Session content is labeled as historical; unknown size or hash is not filled with zero or an empty value.
- Runtime usage and `chat skill feedback` work before a refresh. Humans can leave feedback from a saved source.
- **Start improvement session** pins the repository, root, branch, and commit. Repeating the same request returns the original Session, even before the skill has a history ID. Choose a workspace skill's Agent from collaborators of the improvement Project.

Platform skills are read-only. Send improvement feedback to aachat instead of editing them in the project or agent repo.

## Basic improvement loop

1. Read the observation coverage and feedback to select a skill to improve
2. Edit the workspace repo for a Team-specific skill, or the agent repo at `AA_AGENT_DIR` for an Agent-specific skill
3. Test, commit, and push
4. Use it in a new Session and inspect usage and feedback. Refresh the source to update the saved list

Supporting commands are `aachat skills add <skill-name>`, which installs into the normal `.agents/skills/` source, and `chat skill feedback <skill-name> ...`; syntax is in [cli](/en/docs/cli).

## Install from Discover and record the installation

Discover → Skills is the public catalog; the team's **Skills** sidebar is the Skill Ledger. Read the public Skill's source files and requirements first. In the catalog's install action, choose an Agent you own that has a repository and a connected runtime. Review the preparation conversation and explicitly approve the installation. See [Discover](/en/docs/discover) for target selection and fallback behavior.

The installation work must copy or adapt the Skill and its supporting files into `.agents/skills/<skill-name>/` in that Agent's repo, validate them, and commit and push. If a Skill with that name already exists, review the differences and choose how to adapt it before overwriting useful local behavior. New dependency declarations do not install packages or grant secrets; follow [Environment](/en/docs/environment).

After a successful push, the catalog operation is:

```bash
aachat skill install <skill-catalog-id> --agent <agent-name>
```

Use the actual catalog UUID and your target Agent name from the installation flow. This records an **installation receipt**. It does not download files, push commits, restart a Session, or verify usage. Repeating the registration for the same Agent reports that it is already recorded. Only the target Agent's owner can register it.

| Operation | What it does | Completion check |
|---|---|---|
| `aachat skills add <skill-name>` | Uses the external skills installer to place source files in the current directory's `.agents/skills/` (or `--target`) | Inspect files, validate, commit, and push to the intended repo |
| `aachat skill install <skill-catalog-id> --agent <agent-name>` | Records catalog installation for an owned Agent | Registration result; this is not runtime evidence |
| Skill Ledger usage / feedback | Observes projected skills and records use or improvement feedback | Check the source commit and actual usage in a new Session |

If registration fails after the file push, repair authentication, ownership, or the catalog ID and retry only registration. If the receipt exists but the Skill is absent in a Session, check the pushed commit, new-Session timing, and source precedence. A workspace Skill can shadow the installed Agent Skill.

## Publish a Skill on its own

You can publish a Skill without publishing its Agent in Discover. The original Agent's GitHub repository can stay private. In the Agent detail page's Skills section, choose **Publish** for a Skill owned by that Agent. With a repository and connected runtime, the Agent prepares the selected Skill and supporting files in a separate publication repository. Review that content before publishing. Skills supplied by the Team or Platform do not have this publication action.

A standalone Skill does not need an Agent publication profile or `.aachat/public.yaml`. Put `SKILL.md` and supporting files in `.agents/skills/<skill-name>/` in the publication repository, with `aachat.discovery.listed` set to `"true"` in the metadata below. The CLI command in that prepared repository is `aachat skill publish .agents/skills/<skill-name> --agent <agent-name>`. Follow [Discover](/en/docs/discover) for private preparation and the explicit change to public visibility.

Manage each Skill's sync and listing in publication management. Stopping the source Agent's listing or changing its publication repository does not remove standalone Skills. Sync reads public repository changes into the catalog; it does not distribute updates to Agents that installed the Skill.

## Publishing with an Agent and shared metadata

Agent publication and synchronization also read Skills from that Agent's reviewed public repository. Both standalone and bundled Skills use regular UTF-8 files and require all five localized/listing metadata keys below. The two headline and two description values must be nonempty.

This is the complete content of an example `.agents/skills/source-review/SKILL.md`:

```yaml
---
name: source-review
description: Review public sources and record citations.
metadata:
  aachat.headline.ja: 公開情報を出典付きで整理する
  aachat.headline.en: Review public sources with citations
  aachat.description.ja: 公開情報を比較し、事実と推定を分けて報告する手順。
  aachat.description.en: Compare public sources and separate facts from estimates.
  aachat.discovery.listed: "true"
---

# Source review

Read the supplied public sources. Record each source URL, distinguish facts
from estimates, and write a referenced summary. Do not contact third parties.
```

For a Skill bundled with an Agent, `aachat.discovery.listed: "false"` keeps the Skill out of standalone Discover listing, but its files are still public with the Agent repository. A standalone Skill publication requires `"true"`. The flag is a catalog choice, not an access control. The localized metadata describes the Skill in Discover; it does not translate its instructions automatically.

Review the repository's license, private content, and all supporting files before the human owner publishes it. Follow [Discover](/en/docs/discover) for `.aachat/public.yaml`, explicit public visibility, sync, and stopping the Agent/Skill listing. Catalog lineage records a source relationship; it does not automatically install upstream updates into existing Agents.

## Related pages

- Agent repo and when changes take effect: [agents](/en/docs/agents)
- Session projection: [sessions](/en/docs/sessions)
- Collision and setup failures: [troubleshooting](/en/docs/troubleshooting)
- Command syntax: [cli](/en/docs/cli)


---

# Session — the execution unit where agents work

> The exact specification of session state transitions, starting and continuing sessions, reading transcripts versus logs, how workspaces are created and repo configuration, scheduled execution, and delegation between agents.

# Session — the execution unit where agents work

A session is the execution unit in which an agent actually works. When a user or another agent sends a request, a session starts, and the agent runs on top of the coding agent on the owner's machine ([Trust Boundary](/en/docs/trust-boundary)). This page covers the session lifecycle, operations, how to read the records, workspace separation, and delegation between agents.

## Lifecycle

States transition as `starting → running → stopping → stopped`. Abnormal termination becomes `failed`. A runtime prompt execution failure is distinct from notification delivery failure. Read the transcript and owner-local logs, then check Resume eligibility; Workflow Steps use Workflow retry ([recovery](/en/docs/troubleshooting)).

For an ordinary Session, the policy is for the agent to run `chat session finish` before ending the turn once the current request is fully handled and there is no specific continuation planned. If finishing is already underway, it should not repeat the command. After `chat wait` is accepted, the agent ends only the turn and waits for continuation without finishing the Session (see “Wait for results and continue the same Session” below).

Application of this instruction depends on the owner-side runtime version; it does not guarantee that every running Session stops immediately when its work is done. Acceptance of finish also differs from actual termination. See the [CLI finish explanation](/en/docs/cli) for the subsequent asset wrap-up and other details.

A Workflow Attempt follows its Step completion procedure; ordinary Session finish is not a substitute ([Workflows](/en/docs/workflows)). A Session ending does not by itself establish that the Project is Done, its deliverables are accepted, or code delivery succeeded. Use “Read results and the accepted turn” below to inspect the artifacts and validation.

After 60 idle minutes, a session enters its finish path. When it has a completed turn, the runtime performs `finish` on its behalf and runs one asset wrap-up turn to check for unsaved deliverables before closing. If submitting the initial idle-finish request fails, the session stays alive so that request can be retried. If the wrap-up turn itself cannot start, complete, or persist, the session becomes `failed`, preserves its workspace, and instructs the user to resume it or start another session. Idle finish is disabled while a scheduled follow-up has a next run pending.

Archiving a Project does not forcibly stop work already executing in ordinary Sessions. It does cancel that Project’s unexecuted reservations and block new execution and follow-up instructions. See [Projects](/en/docs/projects) for Workflow Session termination and reservations or recurring work that are not restored automatically.

## Starting a session

```bash
aachat session run <agent> --project <project> "request text"
```

The agent is resolved as a member of the specified project. A session can run only when all three of the following conditions are met.

- The project's status is `active`
- The agent is a member of that project
- `aachat up` is running on the agent's owner side (the agent is online)

In the WebUI, a session starts when you address an agent with the composer's **target chip** and send.

**An @mention is not a session execution trigger.** The exact `@<agent>.<owner>` in a message body is a notification (a call-out) and does not start a session on its own. What makes an agent work is target chip addressing in the WebUI, and `session run` in the CLI. Reports of "I mentioned the agent but nothing ran" are caused by this specification.

The WebUI composer also accepts an attachment-only request with no message text. The attachment is stored in Session history and is not automatically published to Project Media.

### `session run` options

| Option | Meaning |
|---|---|
| `--repo <owner/repo>` | Override the workspace repository for this session |
| `--runtime <claude-acp\|codex-acp>` | Select this session's Runtime. Omission and saved interactive launch preferences follow [Agents](/en/docs/agents) |
| `--config <ID=id:VALUE\|boolean:BOOL>` | Set one explicit Runtime option. Repeat for multiple options; for example, `--config mode=id:plan` |
| `--attach <PATH>` | Attach images, videos, or PDFs. Attachments go to Session history and are not published to Project Media. An attachment-only start without text is valid |
| `--stdin` | Read the request text from stdin (mutually exclusive with the message argument) |

For runtime Permission, a temporary question, a Project Ask, or a Workflow Decision, use the [response comparison](/en/docs/permissions) to choose who answers and what continues.

## Continuing a session

Send additional instructions to a running session with `session send`. When waiting for a registered Ask continuation, do not send the same answer again as a follow-up; see “Wait for results and continue the same Session” below.

```bash
aachat session send <session-id> --project <project> "follow-up instruction"
```

| Option | Meaning |
|---|---|
| `--cancel-current-turn` | Cancel the running turn before executing this message |
| `--attach <PATH>` | Same as `run`. Goes to Session history, not Project Media. An attachment-only send without text is valid |
| `--stdin` | Read the message from stdin |

In the WebUI, the workspace panel opened by selecting a Session in the Project Work Panel lets you monitor execution in real time, send follow-ups, respond to permissions, and cancel turns ([WebUI](/en/docs/webui)).

List sessions with `aachat session list` (the connected team's Work Index; filter with `--agent` / `--project`); stop one with `aachat session stop <session-id>`.

## Reading the records — transcript and logs as a pair

There are two kinds of session records, differing in content and storage location. Use them as a pair.

| Command | What it reads | Storage |
|---|---|---|
| `aachat session read <session-id> --project <project>` | The conversation transcript (requests, responses, progress) | server |
| `aachat session logs <session-id>` | The runtime's stderr log (startup and execution errors) | Local (`~/aachat/.run/logs/`) |

Use `read` to check conversation content and results; use `logs` to investigate startup failures and execution errors. `read` supports paging with `--last` (default 50, max 100) and `--before`. `logs` can read from the beginning with `--from-start`.

Turn completion text is stored in this server transcript but is **not automatically posted as a Project Timeline message**. A handoff remains in the transcript first. When the project needs a short notification or handoff, the agent explicitly runs `chat send <project> ...`. Use a normal Shared Document only when the handoff is substantial and independently worth rereading. Do not put progress or handoffs in `PROJECT.md`. A transcript is the session record; a Timeline message is project-wide communication.

## Compacting a long session

`chat session compact` compresses a long session's context so work can continue in that same session. It does not start new work. Outside agents use the public `aachat session compact` command instead of `chat`.

```bash
chat session compact
chat session compact <session-id> --project <project>
aachat session compact <session-id> --project <project>
```

- With no target it compacts the current session; a target requires its project
- The request runs after the current turn completes and before an ordinary follow-up. Do not pack more work into the turn that requests compaction; finish that turn
- If the runtime does not support compaction, use `chat session finish` to preserve assets, then start a fresh session
- CLI / server request identity makes retries idempotent; do not send a home-grown compression prompt
- Compaction does not delete the original transcript. Keep important decisions and deliverables in canonical Shared Documents rather than relying on the summary alone

## Accepted work after a runtime restart

With a supporting API/runtime version, pending or interrupted work accepted before a restart can recover in the same Session and workspace when its conditions are met. These include restoring saved runtime connection information, workspace and launch configuration with current Project coverage, meeting close/Archive constraints, and staying below the redelivery attempt limit. Automatic recovery of every job and exactly-once external operations are not guaranteed.

A return to `starting` after restart alone does not mean a new request or failure. Before running or sending the work again, inspect the original Session, accepted turn, transcript, results, and delivery. Recovery of accepted work differs from manually resuming an ended ordinary Session. A terminal Workflow Attempt still follows Run retry/new Run rules, not generic Resume. See [Troubleshooting](/en/docs/troubleshooting) for the check order and what to do if progress stops.

## Workspace separation and how workspaces are created

Each session gets an independent workspace created at `~/aachat/.run/workspaces/<agent>--<sid8>` (sid8 is the first 8 characters of the session ID). At session start, the runtime prepares the following.

- **workspace repo**: in a session whose repo is resolved, that repo is checked out at the workspace root. The branch is the aachat-managed `aachat-sessions/<project>/<agent>/<sid8>` (for a session spanning multiple projects, `<project>` is `multi`). A session whose repo is not resolved (a DM, or a team with no repo configured) gets a repo-less empty workspace (scratch)
- **agent repo**: the agent's own repo is checked out as a worktree at `aachat/agents/<agent-name>/`. The session can locate it via the environment variable `AA_AGENT_DIR`
- **Runtime context projection**: aachat's runtime context is generated into `.claude/CLAUDE.md` (Claude runtime) or `AGENTS.md` (Codex runtime), and skills are projected. If the repo already git-manages a file of the same name, the projection is diverted to `CLAUDE.local.md` / `AGENTS.override.md`. Projected files are added to git's local exclude, so they never show up as repo changes

**Cleanup when a session ends** is decided automatically: if uncommitted changes, or local commits that do not exist on the remote, remain, the workspace is **kept**; if it is clean (no changes, or committed and pushed), it is **deleted**. This keep/delete decision **applies only to git workspaces**: a repo-less scratch workspace is deleted at session end regardless of its contents, so move anything worth keeping to a project surface (Shared Documents, media, etc.) before the session ends. The workspace of a resumable session is protected from deletion, and the same workspace is reused on resume.

One session has one workspace repo. Work that spans multiple repos is split into one session per repo and coordinated at the project level. Even when multiple sessions run in parallel against the same repo, each works in its own independent workspace, so in-progress files never collide directly. Changes are integrated through the normal git / PR flow.

### Configuring the workspace repo

The repo resolution order is **the session-level override > the project setting > the team default**.

| Where it is set | How to set it |
|---|---|
| session (one-time override) | CLI `session run --repo <owner/repo>`; in the WebUI, the composer's **Repo chip** |
| project setting | Specify the repository (`owner/repo`) and working branch in the project settings |
| team default | Specify at team creation (WebUI "Create Team" / `aachat team create --repo`) or in the team settings' repository |

A session-level override must match either the project setting or the team default. An `owner/repo` that matches neither is rejected (this is not a mechanism for pointing at arbitrary repos). DM sessions are always scratch; no repo is used.

Note that the WebUI sidebar's "Repository" tree (the GitHub App connection) is a separate system from this setting ([WebUI](/en/docs/webui)). The `aachat init` repo connection ([Connected Repo](/en/docs/connected-repo)) is also not a workspace repo setting.

A team default repo does not grant repository access. Each member needs their own GitHub credential, read/write permission, and organization SSO authorization where required ([Teams](/en/docs/teams)).

## Delegation — an agent driving another agent's session

An agent running inside a session can start, monitor, and continue another agent's session with the `chat` command. `chat` is exclusively for agents inside a session; outside a session (humans, external agents), use `aachat`.

| Operation | Command |
|---|---|
| Start another agent's session | `chat session run --agent <agent> --project <project> "request text"` |
| Read progress and results | `chat session read <session-id> --project <project>` |
| Send additional instructions | `chat session send <session-id> --project <project> "follow-up instruction"` |
| Resume an ended session and send instructions | `chat session send <session-id> --project <project> --resume "follow-up instruction"` |

Before delegating, read `chat project members <project>` and use `members[].name`, `capability.commands`, and `live_sessions` to choose the target. Use `run` for fresh work; use `send` only when there is a clearly related session. To continue the same work in an ended session, explicitly add `--resume`. An advertised slash command is placed at the beginning of the request prompt; it is not a dedicated flag.

`--resume` is an explicit agent-only operation. For a `stopped` or `failed` target, the resume and follow-up are accepted in the same database transaction. If a resume is already in progress, the follow-up is queued in that generation; if the target is `running`, it is accepted as an ordinary follow-up without restarting the session. A plain send never resumes an ended session implicitly. Archived sessions, Workflow Steps, and sessions whose workspace, configuration, or project coverage cannot be safely restored are rejected. Do not combine `--resume` with `--cancel-current-turn`.

Delegation has two conditions: the delegate agent is online (`aachat up` running on its owner's side), and the delegate is a member of the same project. Agent mentions use the exact project-member name `@<agent>.<owner>`. An unknown target produces a warning, and a mention still does not start a session. The same loop humans run in the WebUI — request → execute → check → follow up — works between agents. Delegation requests and results remain in session transcripts; use a message for a short project-wide handoff, and a normal Shared Document for an independent deliverable ([Concepts](/en/docs/concepts), [Shared Documents](/en/docs/shared-documents)).

A session started by delegation records its lineage to the session that started it (the source session). Because which request spawned which session can be traced afterwards, the history stays traceable even as work passes between agents.

### Orchestration patterns

Use immediate Session delegation when the next request depends on the work you are inspecting. Use a [Workflow](/en/docs/workflows) when you want repeatable Steps with typed inputs, outputs, dependencies, and human Decisions. A Workflow pins its Revision for each Run; ordinary delegation keeps the next instruction flexible.

- **run versus send**: `chat session run` starts new work as a new session. `chat session send` adds instructions in an existing session's context; add `--resume` only when continuing the same work in an ended session
- **Waiting for completion**: register explicit targets with `chat wait` as described below in “Wait for results and continue the same Session.” After acceptance, end the turn without polling. Read the results when continuation arrives
- There is no implementation limit on delegation depth or fan-out. Deep chains make the history hard to follow, so consolidate results in the project's Shared Documents

When a human drives multiple agents from the WebUI, the composer's target chip addresses one agent per message. To reach multiple agents, split the request into separate sends or entrust the delegation to an orchestrator agent.

### Wait for results and continue the same Session

When a Session agent needs to use results in a later turn, register explicit target IDs with `chat wait --all` from the current Project directory. Targets are Project Asks, direct child Sessions, or top-level Workflow Runs started by the source agent, all in that Project; they are never discovered automatically.

```bash
cd aachat/projects/<team>/<project>
chat wait --all --ask <ask-id>
# Inspect the wait ID returned at registration when needed
chat wait show <wait-id>
```

After acceptance, end the turn. While waiting, do not use `chat session finish`, re-register, send a manual follow-up, or poll. Once every registered target settles, one continuation is accepted. Ask cancellation is also settled; it does not mean approval or success. The check runs on a 30-second cycle, not a promise of a response within 30 seconds.

#### Find the wait and read its result

The following displays require a Web/API version that supports wait details and result notifications. If they are absent, check the registration receipt in the transcript and use the [CLI read commands](/en/docs/cli); absence alone proves neither an unregistered wait nor success.

A Session can be `running` while its list entry shows **Awaiting results**. Open that Session to find the wait panel above the composer. A single target is a row; expand a multiple-target group to see each Ask, Session, or Workflow name and state. Follow its link to the details. Deleted targets have a fallback name with a short ID and a disabled link. **Couldn't load wait details. → Retry** reloads these details; it does not resend an answer or continue the Session.

After all targets settle and continuation acceptance succeeds, the transcript stores a collapsible **Wait completed** system notification. If every target is settled but the notification is still absent after a check cycle, inspect whether the source Session is `stopping` or archived and whether its agent still has Project collaborator access. Expand a saved notification to inspect the names and states captured at settlement and follow the target links. Later renames or answer revisions do not rewrite this snapshot. **Needs attention** means a target is `failed`, `attention_required`, or `cancelled`. A `stopped` Session also does not by itself prove a successful deliverable.

Keep six checks separate: the answer was saved; every target settled; the target results succeeded; the system notification was saved; it was delivered to the agent; and the agent produced the next result using those inputs. **Delivery pending / failed / cancelled** describes notification delivery, separately from the target snapshot. Open a failed notification for its error and, when eligible, **Retry delivery**. It retries the same notification and turn; it does not rerun the targets. System notifications cannot be edited, removed, or sent with **Run now** like ordinary queued messages.

The agent receives target results with `Read:` commands and reads only the sources needed for its decision. The Web notification presents results and links, not raw commands to copy. `chat wait show` remains an optional read-only check. For retry conditions and Session failure, follow [answer and continuation recovery](/en/docs/troubleshooting).

See [Projects](/en/docs/projects) for saving answers and distinguishing registered from unregistered waits. `chat ask wait --timeout` bounds a wait within the current turn; it does not register this continuation ([CLI](/en/docs/cli)).

### Runtime built-in subagents

A Task tool or similar subagent started by Claude Code / Codex is a **runtime feature for exploration or parallel work inside the same session**. It does not start a separate project-member agent session and does not gain independent project membership, transcript, or handoff ownership.

Use `chat session run --agent ...` when work belongs to a worker with another agent repo, owner, and project role. Use a runtime built-in subagent for temporary division of work inside the same session.

## Scheduled execution

Automatic execution uses Project Triggers and scheduled follow-ups. Triggers are managed in the WebUI or with `chat trigger` inside an aachat Session; scheduled follow-ups can also be created, listed, or cancelled with `aachat session schedule`. Cron expressions are not used.

| Mechanism | Target | Recurrence | Where to configure |
|---|---|---|---|
| **Project Trigger** | Starts a published Workflow or fresh Session | Time conditions may recur; Document match is one-time | Project **Triggers** or `chat trigger` |
| **scheduled follow-up** | Sends a follow-up turn to a running or waiting session | Yes (1-minute to 1-day intervals) | The **Schedule** button in the session thread composer |

- A Project Trigger has exactly one When: Once, Daily / weekly, Interval, or Document match. Document match starts once when Shared Document frontmatter in the same Project equals the configured value. The composer When chip can carry the current agent, prompt, and launch settings into Trigger creation
- A **scheduled follow-up** supports turn execution such as "run this check every morning." It is text-only; replies and attachments are not supported. While a next run is pending, the 60-minute idle auto-stop does not apply. Delete the follow-up or end the session to stop recurrence

## Read results and the accepted turn

Open a Session from the Project Work Panel. Inspect its direct child Session tree to follow delegation, and read each child's final response and actual artifacts. Workflow result badges open the Workflow; Trigger result badges identify the Trigger but do not directly open its detail. Go to the Project's When/Triggers surface and locate that Trigger to inspect its state and occurrences. Open documents through the Project's Docs or the actual document links in the transcript. The results panel is not a complete attribution list for every document or Ask.

A stopped Session is an execution state. Check both repositories in [Code Delivery](/en/docs/code-delivery), then read the submitted content and validation before accepting the outcome. **Pin session / Unpin session** in the header changes your personal pinned list; it does not keep execution running or guarantee workspace retention.

From a human's terminal or an external coding agent, choose the read that answers your question:

```bash
aachat session read <session-id> --project <project> --team <team> --decision
aachat session read <session-id> --project <project> --team <team> --submission <turn-id>
aachat session read <session-id> --project <project> --team <team> --last 50
```

`--decision` returns a bounded view of purpose, latest final text, pending submissions, and child context. Read `gaps` and follow `next_read`: truncated text or unavailable artifact attribution is not complete evidence. Use `--submission` to reconcile one accepted instruction; take the exact `turn_id` from `data.submission.turn_id` in the original run/send receipt. It follows that submission's phase, not simply the latest turn. Runtime acknowledgement is not an independently observed start timestamp or a successful result. Follow its suggested read for transcript evidence.

Both flags are mutually exclusive and belong to public `aachat`, not Session-scoped dispatch or `chat`. For ordinary transcript history, use `next.before` with `--before`.

### Tool output and results you can read later

Current aachat versions do not store tool output in newly saved permanent Session history. Tool inputs, identifiers, and status are retained, but size limits can also omit inputs, so full text is not guaranteed. Output or diffs visible live during execution may be absent when you reopen history. History reads and searches cannot recover output that was not saved. This policy alone does not establish that all older history or data in other storage has been deleted ([storage boundary](/en/docs/trust-boundary)).

Missing output proves neither that the tool returned an empty result nor that execution succeeded or failed. Reconcile the saved status and final response with the actual artifacts, and leave results you cannot verify explicitly unconfirmed. Do not rerun an operation solely to fill in missing output.

Put confirmed results, judgments, sources, and remaining uncertainties needed for later decisions into independently readable artifacts such as [Shared Documents](/en/docs/shared-documents), and point to them from the Session's final response. Select the necessary evidence and exclude secrets instead of copying raw output wholesale. Adding a document does not recover output that was never saved.

### Search saved transcripts

A Session agent can search as follows with a chat/API version that supports it. If `chat session read --help` does not list `--match`, check the installed version. Public `aachat session read` does not have this flag.

```bash
chat session read <session-id> --project <team>/<project> --match 'cargo test' --last 20
```

The scope is searchable text actually retained, such as saved conversation and tool inputs in **both the specified Session and the specified Project**. Unsaved or omitted output and image contents are not searchable. Matching trims surrounding whitespace and treats the remainder as one case-insensitive literal using Unicode case folding. It does not split whitespace-separated terms or use wildcards or regular expressions; an empty value after trimming is rejected.

`--last` limits the number of excerpts (default 50, maximum 100). The newest matches are selected and returned in history order. One message may yield several excerpts, so the count is neither a message count nor a total match count. Each body excerpt is at most 600 Unicode scalars, with a separate tool identification header in some cases. Excerpts are not full text, and an ordinary read does not guarantee full tool output either.

Pass an ordinary read's `next` to `--before` to search history older than that cursor. Match responses have no next-page cursor, and scanning stops at the limit; neither all history nor all matches are guaranteed. Narrow the search text if the result reaches the limit. An empty successful response means no match in saved searchable text for that Project and search window. Read failures such as 403, 404, or timeout are not a negative search result ([Troubleshooting](/en/docs/troubleshooting)).

## Related pages

- The agent repo structure and when changes take effect (next session after push): [Agents](/en/docs/agents)
- Project status and member management: [Projects](/en/docs/projects)
- Starting from an external system with a credential: [External Session Runs](/en/docs/external-session-runs)
- Triage when sessions will not start or responses stall: [Troubleshooting](/en/docs/troubleshooting)
- The full command surface: [CLI](/en/docs/cli)


---

# Start Sessions from an External System

> The credential, HTTP request, idempotency, and rotate/revoke contract for safely starting a new session with a fixed agent, mode, and repo from GitHub Actions, CI, or a webhook.

# Start Sessions from an External System

External Session Run lets GitHub Actions, CI, a webhook adapter, or another system outside aachat send new work to a project agent. It is separate from interactive `session run` and from scheduled starts configured inside the WebUI, and has its own credential boundary.

Before using it, confirm that the project is active, the target agent is an active Admin / Collaborator, and the owner's runtime can start sessions.

## Create a credential

Open **Start from external app** on the project screen and choose an agent. Only the current human owner of that agent can manage its credentials, and that human must also be a project Admin / Collaborator.

Creation fixes the following authority:

- credential name
- target agent
- a launch mode advertised by that agent
- workspace repo resolved from the project / team
- optional expiry

After creation, the screen shows `AACHAT_API_URL` and `AACHAT_API_KEY`. **The API key is shown only then and cannot be read back.** Store it in a secret store or untracked `.env`; never put it in a repo, log, or document.

## Send a request

```bash
curl -fsS -X POST "$AACHAT_API_URL?wait=started" \
  -H "Authorization: Bearer $AACHAT_API_KEY" \
  --json '{
    "text": "Run the external check and report the result.",
    "idempotency_key": "github-run-12345"
  }'
```

- `text` is the request delivered to the session
- `idempotency_key` is a stable unique ID for the external event. Retrying the same request with the same key does not start a duplicate session
- Reusing an `idempotency_key` with different text, metadata, or execution context is a conflict. Use a new key for new work
- `?wait=started` waits for the runtime to acknowledge session start. Without it, the response returns when the request is accepted
- An optional `metadata` object can correlate the invocation with the external event

Use response `status`, `session_id`, and `web_url` to confirm the start. A request may be accepted and later fail to start at the runtime, so inspect the existing invocation before retrying the same work.

## Rotate, revoke, and expiry

- **Rotate** issues a new token and invalidates the old one. Update the caller's secret immediately
- **Revoke** stops new requests through that credential
- An expired credential cannot accept new work. Issue a new credential and update the caller for a new invocation

New work through an otherwise active credential is rejected when the project is not active, its creator is no longer a project Collaborator, the agent's owner changed, or the agent is no longer a project Collaborator. A credential never bypasses current membership.

An exact retry can still return an already-accepted invocation after revocation, expiry, or a membership change, as long as the token is still recognized. These checks protect new work; they do not erase earlier acceptance. Rotation replaces the token while keeping the credential ID: the old token is no longer recognized, so retry with the new token and the same key/body. A revoked or expired credential cannot be rotated. A newly created credential has a different ID and a separate idempotency scope.

## Connect a CI event without duplicate work

Give each intended piece of work a stable event key. For GitHub Actions, a repository, workflow run ID, and operation label identify one request. Do not include the retry attempt if rerunning a CI job should only recover the same invocation. Include an explicit new work identifier only when you intend to start another Session.

The following shell step requires `curl` and `jq`. Configure `AACHAT_API_URL` and `AACHAT_API_KEY` using the credential screen's values, and inject them through the CI environment. It constructs JSON safely rather than interpolating event text into a JSON string. Keep the same body and credential for transport retries.

```bash
# Supply AACHAT_API_URL and AACHAT_API_KEY through your CI secret settings.
# GITHUB_REPOSITORY and GITHUB_RUN_ID are provided by GitHub Actions.
set -eu
request_file="$(mktemp)"
trap 'rm -f "$request_file"' EXIT
jq -n \
  --arg event_key "github:${GITHUB_REPOSITORY}:${GITHUB_RUN_ID}:source-review" \
  --arg repository "$GITHUB_REPOSITORY" \
  --arg run_id "$GITHUB_RUN_ID" \
  '{text: "Review the public sources and report findings in this Project.",
    idempotency_key: $event_key,
    metadata: {repository: $repository, run_id: $run_id}}' > "$request_file"
curl --silent --show-error --fail-with-body \
  --request POST "$AACHAT_API_URL?wait=started" \
  --header "Authorization: Bearer $AACHAT_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary "@$request_file"
```

Do not enable shell tracing (`set -x`) or print the credential environment. Keep metadata to non-sensitive correlation information: it is part of the request stored by the server. The idempotency key must be nonblank and at most **200 UTF-8 bytes**; metadata must be an object that serializes to at most **8192 bytes**. Shorten a key deliberately if the repository and label make it too long, preserving uniqueness.

A key is scoped to its credential ID. The same key with the same normalized text, metadata, fixed launch specification, and workspace context returns the existing invocation. Metadata object key order alone does not make a different request. Changing any of those contents conflicts. A different credential is not a way to retry the same invocation safely.

## Read acceptance, start, and failure separately

| Response state | Meaning | Next step |
|---|---|---|
| `accepted` | The server recorded the invocation; start is still pending | Preserve `invocation_id` and the exact request. An identical retry can retrieve the current result |
| `started` | The runtime acknowledged Session start | Follow `session_id` / `web_url` and inspect the actual result in the Session |
| `failed` | The invocation could not complete startup | Read `failure.code` and `failure.message`, correct the cause, and use a new key only for a deliberate new attempt |

`wait=started` has a bounded wait and may still return `accepted`. It does not wait for task completion. HTTP success alone does not mean the work succeeded, and `web_url` can be absent until a Session is bound. Store the returned invocation ID and Session link as correlation evidence in your CI output, then check the Session's work and deliverables in aachat.

On a network timeout or lost response, retry the **exact request with the same credential and key**, rather than generating a new timestamp key. This can recover the existing invocation. A failed invocation remains that invocation; repeating its key does not create a fresh attempt. A wrapper that needs to retry actual failed work must make that choice explicit and inspect the previous result first.

## Diagnose the failing layer

- For an unauthorized, expired, or revoked credential, check the caller's secret and the credential screen. After rotation, replace the caller's old token. Never paste a key into a support message.
- For an authority failure, check that the Project is active and that the human owner and Agent still satisfy the Project membership rules. A key cannot add membership.
- For a validation error, check nonempty text, key length, metadata shape/size, and the `wait` value (`accepted` or `started`).
- For an idempotency conflict, compare the original request and execution context. Do not silently turn it into a new key and duplicate work.
- For startup failure, check the owner's runtime, fixed launch configuration, and access to the fixed workspace repo. Correct those prerequisites before deliberately starting again. If a different target or launch context is required, create an appropriate new credential.

Rotation, revocation, and expiry control use of a credential; they are not Session cancellation or rollback of work already started. Use the [Session controls](/en/docs/sessions) to manage that work. This endpoint starts a Session and does not publish or run a Workflow from a webhook.

## Related pages

- Interactive sessions and workspaces: [sessions](/en/docs/sessions)
- Team / project roles: [teams](/en/docs/teams), [projects](/en/docs/projects)
- Server storage boundary for credentials: [trust-boundary](/en/docs/trust-boundary)
- Start failure diagnosis: [troubleshooting](/en/docs/troubleshooting)


---

# Team — Visibility, Roles, and Member Lifecycle

> This page covers public/private teams, Discover Teams, Owner/Admin/Member authority, invitation and removal lifecycle, deletion, and the credential boundary of the default workspace repo.

# Team — Visibility, Roles, and Member Lifecycle

A team groups humans, agents, projects, and company context. This page is canonical for the team's visibility and member management. Project Admin / Collaborator / Viewer are separate roles covered in [Projects](/en/docs/projects).

## Create a team

From WebUI Home → Teams → **Create Team**, set a name, vision, visibility, and optional default workspace repo. The CLI is `aachat team create <slug> --repo <owner/repo>`.

- **public**: Discover Teams shows the name, vision, and member count without sign-in
- **private**: the team is not exposed to non-members
- A personal team (`~<login>`) is created automatically at sign-in. It is a fixed personal surface and does not follow all ordinary team publication, deletion, and leave behavior

Public visibility publishes the existence of the team. It does not expose private projects or member-only Timelines and Documents.

## Team roles

| Role | Primary authority |
|---|---|
| **Owner** | Team settings, role changes, member removal, and team deletion |
| **Admin** | Team settings and invite-link management. Cannot change/remove an Owner or perform owner-only operations |
| **Member** | Uses projects and team surfaces to which they have access |

A team must keep at least one Owner; the last Owner cannot be demoted or removed. Only Owners change roles and remove members. Owners / Admins issue invite links in Team Settings, and a human opening one joins immediately as a Member. Rotate a link if it may have leaked.

## Leave, removal, and deletion

- When a human leaves or is removed, their project memberships in the team and the project assignments of agents they own are also removed
- Leave Team is not shown to an Owner. Establish another Owner and change roles first
- Team deletion is an irreversible Owner operation. Usable access to the team's projects, messages, and agent assignments is permanently lost, with no restore path. Confirm project assets and member migration first
- A personal team cannot be left

Use a team invite for an ongoing colleague, a project join link for a project-only collaborator, and client entry for a short-term client without a GitHub account ([Projects](/en/docs/projects), [Connected Repo](/en/docs/connected-repo)).

## Default workspace repo

A team default workspace repo is used when no more specific repo is set on the project or session. [Sessions](/en/docs/sessions) is canonical for repo resolution order.

This setting does not share or grant GitHub access. Every member running a session needs their own GitHub credential, repo read/write permission, and organization SSO authorization where required. The GitHub App used by the WebUI Repository tree and an `aachat init` connected repo are separate systems.

## Related pages

- Project roles and join links: [Projects](/en/docs/projects)
- Workspace repo resolution: [Sessions](/en/docs/sessions)
- Screen locations including Discover: [WebUI](/en/docs/webui)
- Client entry and connected repos: [Connected Repo](/en/docs/connected-repo)


---

# project — where the context of work lives

> Project kinds (project / stream / dm), status and executability, Project Timeline input and output, member management and invitations, and Asks. Answer questions about projects from this page.

# project — where the context of work lives

A project is the unit of work — the place where requests, history, decisions, and deliverables accumulate. In the two-layer context structure of [Concepts](/en/docs/concepts), a project is the "context of work" layer. It is the counterpart concept to an agent's own memory (the agent repo), so answer questions about which of the two something belongs in based on [Concepts](/en/docs/concepts).

Project members are both humans and agents. Members of the same project can see all conversations and deliverables within that project. That is why handing work off between agents requires no re-sharing of information.

## project kinds

There are three project kinds.

| kind | Purpose | Participants |
|---|---|---|
| `project` | A regular project for getting work done | Chosen members (humans and agents) |
| `stream` | Team-wide announcements and casual chat | All human members of the team |
| `dm:<agent>` | One-on-one with an agent | You and that agent |

A **stream** exists exactly once per team and is created automatically when the team is created. It is human-only: agents cannot join, requests cannot be issued there, and agents can neither view it nor be mentioned in it. It cannot be deleted, its name and settings cannot be changed, and members cannot be added or removed (it follows the team's membership as-is). An `@name` mention delivers a notification to that person's Feed. Use it for discussion before something becomes a project, cross-team announcements, and casual chat; write anything an agent should read in a project. Streams are excluded from search (`find`).

A **dm** is created automatically in the owner's personal team when an agent is created (or cloned from Discover). Only the owner can see its contents. Sending with the agent selected as the target starts a session; sending without a target just leaves a regular message and does not start a session. It is suited to trial requests and agent tuning before bringing work into a project.

Issue work requests in a regular project from the start. stream and dm are places for conversation before — or instead of — bringing something into a project.

## Status and executability

A project has four statuses, and new projects start as `active`. **Starting a new Session or sending follow-up instructions requires an active Project with no Archive in progress.**

| status | WebUI label | Intended state |
|---|---|---|
| `planning` | Planning | Not yet started |
| `active` | In progress | In progress (default) |
| `completed` | Done | Finished |
| `archived` | Archived | Put away |

In a non-active project, running sessions and sending follow-up instructions, sending messages, **viewing the timeline and Shared Documents**, adding or changing members, and editing join links all become unavailable. The project is also excluded from search, mention lists, and Inbox (unread). Archive preserves history. A Project can be archived from planning, active, or completed, but returning it to active does not restore cancelled work. Check the effects in the steps below before archiving.

A Project Admin can choose Done from the status menu in the header. First review and accept the results using “Review results and complete the Project” below. Done (completed) records completion after reviewing results; Archive stops work and puts the Project away. A successful Archive does not establish that the outcome was achieved.

### Check the effects before archiving

1. **As a Project Admin, open Settings → Danger Zone → Archive.** The Archive action shown in the sidebar, or **Archived** in the header’s status menu, opens the same confirmation. Projects in planning, active, or completed can be archived. Opening the confirmation does not start the operation.
2. **Read the counts of Workflow Runs to cancel and Workflow Sessions to stop.** Work already executing in ordinary Sessions is not forcibly stopped. However, this Project’s unexecuted reservations are cancelled, future scheduled follow-ups are ended, and active Triggers are paused. Check that these effects are appropriate for the work.
3. **Resolve any blocking child Projects or Workflow Sessions first.** Review an active child’s results before marking it Done, move it to a parent that meets the requirements, or check its effects and archive the child. For a Workflow Session that also covers other Projects, finish its work and reopen the confirmation. See [Troubleshooting](/en/docs/troubleshooting) for reparenting requirements and the different rejection reasons.
4. If you accept the effects, choose **Archive**. The button reads **Stop and archive** when there are running or waiting_for_decision Runs, or Workflow Sessions to stop. A button labelled Archive can still cancel Runs such as those in attention_required, so read the counts. Before submitting, use Back to leave. **Once accepted, cancellation continues even if you close the dialog.** If Trigger configuration/version, reservations, or other work changes and the confirmation has changed, reopen it and check the updated effects.
5. **Archive in progress** means accepted, not completed. Check Remaining Runs and Sessions waiting to stop. The Project becomes Archived after the Workflow Runs reach a terminal state and Workflow Session termination is confirmed. During processing, even if the status still shows active, new execution and follow-up instructions are blocked, as are status changes and deletion. If an error and Retry appear, follow [the Archive recovery steps](/en/docs/troubleshooting).

### Review history or start work again

After Archive completes, an Admin can choose **Unarchive** in Settings to return the Project to active (In progress). From the CLI, find it in the list of all statuses:

```bash
aachat project list --status all
aachat project update <project> --status active
```

To return from Done, choose In progress in the header or use the same CLI command. If the Project has a parent, the parent must also be active with no Archive in progress. If this Project is still being archived, first confirm that Archive has completed.

Restoring the Project does not automatically restart cancelled Workflow Runs or unexecuted reservations, ended scheduled follow-ups, or paused Triggers. Read the preserved history and results, request only the work still needed, and check each recurring task’s settings and state before configuring or resuming it individually.

Permanent deletion is "Delete" in the "Dangerous Actions" card in Project settings (CLI: `aachat project delete <project> --yes`) and cannot be undone. Only active projects can be deleted. When in doubt, choose archive.

## Starting a project

Sign in to the team. If you choose an agent Lead, check that the agent you own has an authenticated, online runtime. See [Setup](/en/docs/setup) for first-time preparation.

1. Open **Projects → New Project**. Leave Parent project unset for your first independent piece of work. Creating a child Project requires an active parent where you are an Admin or the current Lead.
2. Choose a **Lead** responsible for the result. Choose an active human member of the team or an agent you own. For a child Project created through this human entry point, the chosen Lead is added to the parent at creation if needed; prior parent membership is not required.
3. Write the goal, background, expected deliverables, and constraints in **Brief**. Use a **Name** of 2–30 lowercase letters, numbers, or hyphens, excluding the reserved names `stream`, `dm`, and `repo`. The optional catalog note (description) does not replace the Brief.
4. Submit **Create** once. An agent Lead gives “Project created; setup session accepted” and receives a setup Session. A human Lead gives “Project created; human Lead notified” and receives a notification.
5. For an agent Lead, open the accepted Session from the Project's Work Panel and check the Brief, response, Asks, and directions to deliverables. For a human Lead, use the notification to review the Project and Brief, then begin the work as a human. Verify creation acceptance, work progress, and acceptance of results separately.

The agent Lead prepares PROJECT.md and an initial REPORT.md from your Brief and relevant context, using Asks when information is missing. After incorporating the answers and completing both documents, it ends the setup Session. The Project and its Lead remain in place; you choose and request the next work.

For an agent Lead, creation already accepts the setup request, so do not repeat it in the composer. See [Sessions](/en/docs/sessions) for a later request or additional instructions for the same work. If Create is disabled, the Lead is missing, or work does not progress after acceptance, use [Troubleshooting](/en/docs/troubleshooting). Required CLI arguments and Brief input are in [CLI](/en/docs/cli).

### Starting from a Project Template

**Discover → Project Templates** starts from an existing work pattern and is a separate entry point from regular Project creation above. Choose a team and new project name on a public template's detail page. This creates a fresh project with the template's root document and generated Project HTML `index.html`. Advertised folder structures and document templates are not currently applied. Agents are not assigned by the template; assign the needed agents after creation.

A Project Template is a catalog blueprint for a new, independent project; the project does not stay synchronized with it. It is distinct from a [Shared Document template](/en/docs/shared-documents) that installs kind definitions.

### `PROJECT.md` is the project's stable contract

A project's `docs/PROJECT.md` is the Project Contract / Context Router that an agent reads first, on demand, when it needs context. Keep only Purpose, Outcome, Outputs, decision principles and boundaries, a curated Context Map, and a stable Approach. Do not put progress, assignments, handoffs, logs, or unresolved notes there.

The Context Map is a reading route to important canonical sources, not a document inventory. Use generated `docs/index.md` to discover the full catalog. A handoff remains in the session transcript by default; use a message for a short project-wide share, or a normal Shared Document when it is independently worth rereading ([Shared Documents](/en/docs/shared-documents)).

## Project Timeline

The Project Timeline is where a project's requests, history, and decisions remain in chronological order. The WebUI main timeline shows messages and Ask cards. Shared-document create/update is discovered in the Documents surface ([Shared Documents](/en/docs/shared-documents)); sessions are discovered in the Work Panel. The CLI `aachat project read` still mixes document and session lifecycle items into `items[]` for agents.

The Timeline is not a notification that scrolls away; it is a record that stays. The source of truth for deliverables lives in Shared Documents, but the intent of requests, the course of decisions, and the exchanges remain on the Timeline, where the next session and humans can consult them. Results accumulate in three places: Shared Documents, the Timeline, and the agent repo (the flow of company assets in [Concepts](/en/docs/concepts)). When a human needs to notice a document update, write a short message with a WikiLink.

Date and unread separators show your position; **Load older** reads history, and new arrivals can be followed at the latest edge. Session turn completion text is stored only in the session transcript and is not automatically posted as a Timeline message. Project-wide notification requires explicit `chat send` / `project send` ([Sessions](/en/docs/sessions)).

### Rendering

Timeline messages are rendered richly as Markdown.

| Syntax | Display |
|---|---|
| Headings, lists, tables, quotes, checklists | Rendered as normal Markdown |
| Code blocks | Syntax highlighting via language tag. With a copy button |
| Mermaid | ` ```mermaid ` blocks render as diagrams. Follows the light/dark theme |
| mindmap / brainstorm | Structured blocks display as a collapsible tree and idea cards respectively (how to write them is in [Markdown blocks](/en/docs/markdown-blocks)) |
| WikiLink | The `[[aachat/projects/<team>/<project>/docs/...]]` form becomes a clickable chip that opens that document |
| @mention | Highlighted in color. **Mentions are notification-only, not a session execution trigger** (execution is in [Sessions](/en/docs/sessions)) |
| External links | Become links that open in a new tab |

Write a WikiLink in a request body and the agent can read the document at that path to build context. Attached images display on the timeline and enlarge on click.

### Input and output

Timeline input and output are the CLI's `aachat project read` / `aachat project send` (agents use the equivalent `chat` commands inside a session).

```bash
aachat project read <project>
aachat project send <project> "message body"
aachat project send <project> "reply body" --reply-to <seq>
```

What you pass to `--reply-to` is not a message ID but `seq`, the sequential number within the project (included in the output of `aachat project read`). A message posted as a reply shows a quote of the message being replied to; clicking the quote jumps to the original message. In the WebUI, open the inline thread from a root or reply, then reply from the bottom composer.

### deep-link

Opening a project URL with `?msg=<message-id>` appended auto-scrolls to that message and highlights it temporarily. Messages inside a session (Workspace panel) use the form `?session=<session-id>&msg=<message-id>`. URLs opened from search results and Feed notifications use this form, and the parameters are removed from the URL automatically once display completes.

## The project's deliverable surfaces

A project's deliverables go to a different surface per type. The directories under `aachat/projects/<team>/<project>/` in the workspace correspond to the surfaces.

| Surface | Path | What goes there | Details |
|---|---|---|---|
| Shared Documents | `docs/` | Documents to read for decisions and handoffs (the source of truth) | [Shared Documents](/en/docs/shared-documents) |
| Project Media | `media/` | Finished images, videos, and PDFs | [Media](/en/docs/media) |
| Project HTML | `html/` | Browser-viewable prototypes and reports | [HTML](/en/docs/html) |

## Member management and invitations

Both humans and agents become project members.

**Humans** join via invite links. Only humans can use join links.

- **Team invite link** (Team settings → Invite Links; Owner / Admin only): welcomes someone as a member of the team. Joiners are granted the Member role
- **Project join link** (project settings → Join Link; manageable by project Admins only): joins that project only. The granted role can be chosen from Viewer / Collaborator / Admin. Because the team's other projects are not visible, this suits inviting outside collaborators per engagement

With either link, whoever opens it joins immediately at the press of a button, with no approval wait. If a link may have leaked, invalidate the old one with Rotate (reissue).

**Agents** are added from project settings (or the Add Agent button on the project screen).

There are three project roles: Admin / Collaborator / Viewer.

| Capability | Admin | Collaborator | Viewer |
|---|---|---|---|
| View messages and documents | ○ | ○ | ○ |
| Send messages | ○ | ○ | − |
| Add your own agents | ○ | ○ | − |
| Project settings, member management, join link management | ○ | − | − |
| Archive and delete the project | ○ | − | − |

Agents can be given the Admin role, and an agent Admin can add another agent as Admin. However, a project must keep **at least one active human Admin**. Demoting or removing the last human Admin is rejected even when an agent Admin exists. Removing a human member from a project also removes the participating agents that person owns.

## Asks

Asks are the mechanism by which a session agent hands decisions and information that only a human can provide over to humans as questions. **Session agents must always use Asks, not Shared Documents frontmatter.** Outside agents ask the human in their own conversation with the host ask. The question, background, answers, and change history are stored on the Ask itself, so a decision can be reached without creating a document.

**An Ask is immutable, and answers remain as revisions.** Changing an answer adds a new revision, and the earlier decision also stays in the history (Change history). Answered and canceled Asks are never deleted; they remain as the project's decision log.

- **Where they surface**: an Ask card on the project timeline, the Asks panel in the sidebar (with an unanswered-count badge), and Home Feed notifications. Session agents create and wait with `chat ask`. The outside CLI is `aachat ask list|show|cancel|answer`
- **Input**: the assignee is an active human project member. Supply either no choices (free answer) or 2–5 choices. Even with choices, the human may submit a free answer outside them
- **Conflicts**: if another screen saved an answer first, explicitly compare the server answer with your draft and choose to use the latest, overwrite with your answer, or discard the draft. The WebUI does not silently overwrite
- **scope**: `Project` scope is a normal question that can wait for an answer across turns. `Session` scope is a question meaningful only in the current session's context; it gets a `Session` badge in the WebUI
- **Cancellation**: an open Ask can be canceled with a reason by its creator, its assignee, or a project Admin. It is auto-canceled, with the reason kept in the history, in these cases — the Session-scope source session ended / the project is no longer active / the assignee is no longer a project member

### Save an answer and check continuation

Check that the Project is active and you are the Ask's assignee or a Project Admin. Open **Asks** or its Timeline card and read the question, background, scope, and source Session. The panel groups Asks from the same source Session into one card.

1. Select an option into the draft, if provided, and edit a free answer as needed. **Selection alone does not save it**. Use **Save answer** or **Save only**, as shown on your screen.
2. Check the saved answer under **Answered**. Changes remain as revisions in **Change history**. If a conflict appears, compare the latest answer with your draft before using the latest or explicitly overwriting it.
3. If the source Session registered this Project Ask with `chat wait --all --ask <ask-id>`, save and wait for continuation. Find the accepted wait ID and target set in the Session transcript. When needed, a Session agent can inspect it with `chat wait show <wait-id>`.
4. **After every registered target settles**, one continuation turn is accepted for the source Session. If the wait also includes other Asks, Sessions, or Workflow Runs, those must settle too. Check continuation acceptance separately from the results the agent produces using your answer.

For a registered wait, do not also use **Send & continue** or **Send N answers to session**. Continuation may be delayed until the next check, which runs on a 30-second cycle. This does not guarantee a finished response within 30 seconds.

On a version with the corresponding API, database changes, and Web UI delivered, an answer covered by its source Session’s own wait shows **Answer saved. The session will continue when all wait conditions are met.** An answer whose automatic continuation has been accepted shows **Chat continuation accepted**. Answer saving, continuation acceptance, the agent reading the answer, and a successful result are separate: neither display proves reading or success. On versions without these displays, check the registration receipt and source Session above; absence alone does not mean no wait was registered.

When the same card mixes automatic and manual continuation targets, **Send N answers to session** counts and sends only answers needing manual delivery, so its count can be smaller than the number saved. If all answers are automatic targets, no additional manual send is needed. A supported server also checks Ask answer sends from older screens: when all answers are automatic targets, a successful response creates no new turn or message. This does not guarantee deduplication of all ordinary follow-up instructions.

For a normal Project Ask without a registered wait, saving alone does not start a new turn. If the same work needs to continue, check the source state; if running, use a manual send action once to deliver saved answers as a follow-up. For stopped work, see [Sessions](/en/docs/sessions). If registration is unclear, check its acceptance first instead of combining two continuation paths.

Cancellation also counts as settled for a wait; it is not approval or a successful answer. A later answer revision does not fire the same wait again. If the next stage needs the change, deliver it as an additional instruction for the current work. Do not treat Session-scope Asks or Workflow decisions as ordinary Project Ask waits. If saving or continuation cannot be confirmed, use [answer and continuation recovery](/en/docs/troubleshooting).

Automatic acceptance covers revisions up to the answer revision used for that acceptance. A revision changed after acceptance, an answer without a wait from its source Session, or an answer awaited only by another Session is not necessarily covered by the same automatic continuation. Read the revision in **Change history** separately from the current continuation display, check the source Session’s state, and choose any additional instruction needed. Do not assume changing an answer always restarts work automatically.

For **Awaiting results**, **Wait completed**, and notification delivery after answering, see [Sessions](/en/docs/sessions). Use [recovery](/en/docs/troubleshooting) to choose read Retry, Retry delivery, Session Resume, or Workflow Step retry.

## Review results and complete the Project

While the Project is active, the person accepting its results checks the following. Being Lead and holding the human Project Admin role are separate responsibilities.

1. Open `PROJECT.md` from **Docs** and compare the deliverables with its Outcome and Expected Outputs.
2. In the same Docs view, open `REPORT.md` by its title. Read the results, verified evidence, remaining gaps, and next steps; also inspect linked deliverables and Session transcripts.
3. If the REPORT is missing or out of date, ask the current Lead to create or update it. Its location is the Project's `docs/REPORT.md`, with the uppercase filename. See [Shared Documents](/en/docs/shared-documents) for ownership and sync.
4. After accepting the results, a **Project Admin selects Done from the header's status menu**. Check that the status becomes Done (`completed` in the CLI).

An active Project with a Lead cannot complete without a REPORT. Its presence does not automatically establish quality or goal attainment. Review the content before completion instead of creating an empty REPORT just to pass the condition. If the menu is unavailable, ask an Admin. If “Create or update Current report, then retry completion.” appears, follow [REPORT recovery](/en/docs/troubleshooting). See “Status and executability” above for revisiting content and reactivation.

## Change the Lead and inspect delegated Projects

A human Project Admin can open **Settings → General**, choose **Lead**, and save, or send a separate CLI update:

```bash
aachat project update <project> --lead @<member> --team <team>
aachat project delegations <project> --team <team>
```

Choose an active human Team member or an Agent you own. Membership checks also cover the active direct parent and children; if the required membership cannot be added under your authority, resolve that access first. Do not combine `--lead` with description or status changes. The new Lead owns future REPORT updates. Existing REPORT text and Session ownership are not rewritten, and changing Lead does not itself launch replacement work. Active time Triggers created by the previous Agent Lead to start itself in this Project are marked completed; inspect scheduled work and deliberately arrange the next request.

`delegations` returns direct child Projects and their current REPORT summary/version, or marks a missing REPORT. Inside a Session, read `items` and the available access flags from `chat project delegations <parent>` to inspect the child's actual results. A completed child or a summary is not a substitute for reviewing its deliverable.

## Move a child with a handover Brief

Reparent when a child's work belongs under another parent. A human must be Admin of both old and new parents. They must be ordinary Projects in the same Team; the child must be planning or active, the destination active, and the relationship must not form a cycle. A root Project cannot be moved this way. Resolve Archive in progress before moving anything.

```bash
cat > handover.md <<'BRIEF'
Purpose: Move the customer-guide work under the documentation Project.
Current result: The draft is saved in this child's Docs; review it before editing.
Next outcome: Complete the bilingual guide and record validation in REPORT.
Boundary: Preserve this child's artifacts. Do not publish without the required approval.
BRIEF
aachat project reparent <child> --parent <new-parent> --team <team> --stdin < handover.md
aachat project delegations <new-parent> --team <team>
```

Replace the names and Brief with the real work. stdin is plain Markdown text, not JSON. Read the returned old/new parent, disposition, and `lead_action`. An agent child Lead receives a handover Session; a human child Lead receives a signal. `completion_state: accepted` is handover acceptance, not completion of the child's work. The parent relationship and necessary Lead memberships change; existing Sessions do not automatically gain rewritten coverage. Inspect the new parent's direct children and the child's REPORT, then use [reparent recovery](/en/docs/troubleshooting) if the request was rejected.

## Confirm deletion has completed

Delete is irreversible and requires removing or relocating **all** child Projects first, including inactive ones. After confirming the Project, `aachat project delete <project> --team <team> --yes` returns deletion acceptance and an operation ID. Keep that ID. Acceptance does not mean the data has already been erased.

Return to the WebUI's **Deleting** state to read progress; **Deletion failed** exposes the error and **Retry**. An authorized Team administrator can retry the same operation after resolving the cause. Integrations can read `GET /v1/teams/{team}/project-deletions/{operation-id}` using the appropriate identity ([Developer API](/en/docs/developer-api)). Re-read the operation until its completed state; a missing view or an unsuccessful read is not proof of deletion.

Cleanup processes Workflows, Database, HTML, Media and attachment resources before final Project-record removal. Accepted database operations and unresolved migrations can delay cleanup. Public assets and shares should not be assumed erased at request acceptance, nor should every ordinary Session process be assumed to stop instantly. Review in-flight work before choosing Delete; use Archive when you may need to restore the Project. See [Database](/en/docs/database), [Media](/en/docs/media), [HTML](/en/docs/html), and [deletion recovery](/en/docs/troubleshooting).

## Related pages

- How project relates to the session and agent concepts, and the two-layer context structure — [Concepts](/en/docs/concepts)
- Session start conditions and lifecycle, delegation between agents — [Sessions](/en/docs/sessions)
- The Shared Documents contract (source of truth and projection, WikiLink, kind) — [Shared Documents](/en/docs/shared-documents)
- WebUI screens and operations — [WebUI](/en/docs/webui)
- Team roles and visibility — [Teams](/en/docs/teams)
- CLI command details — [CLI](/en/docs/cli)


---

# Company — Concepts, Entities

> Share decision criteria through Concepts and map your company with Entities. Learn registration, proposals, permissions, hierarchy, and when to use Meetings.

# Company — Concepts, Entities

An aachat team holds shared context about the company itself, outside any individual piece of work (project). There are two layers. Concept's internal model (kind, semantic axes, revisions, reviews, links, similarity gate) is canonical in [concept-registry](/en/docs/concept-registry). Entity's internal model is canonical on this page.

| Layer | Content | Where in the WebUI | Detail |
|---|---|---|---|
| **Concept** | The team's agreed Visions, Issues, and Policies. Every agent and human reads them as premises for judgment | Team sidebar "Concepts" | [concept-registry](/en/docs/concept-registry) |
| **Entity** | A map of the persistent, concrete things that make up the company, decomposed to the level where building, improving, maintaining, or retiring each can be decided independently | Team sidebar "Entity" | Below on this page |

## Where to ask

**No dedicated place is needed.** Ask an agent in any project session as with any other request, or ask an outside agent working in a connected repo. Session agents use session authority; outside agents read the same projected YAML and use `aachat registry`, which submits with the signed-in human's Team role.

- **Read**: agents read published Concepts and current Entities and use them as premises for their judgment
- **Proposing Concepts**: agents register new Concepts, revisions, and links as **proposals**. A proposal stays pending, and **a human reviews it on the Concepts screen in the WebUI** to accept or decline. Only accepted Concepts become the team's decision criteria (see [concept-registry](/en/docs/concept-registry))
- **Entities**: agents can register and update Entities (normal kinds only — see below) directly from a session. Unlike Concepts, these take effect immediately, without a proposal-and-review step

In a connected repo, first require the Team projection in `aachat status` to be `healthy`, then read the two indexes, selected individual YAML, and matching Meeting bodies. Saving YAML is only a staged local edit; `aachat registry submit` is the explicit mutation boundary. The server applies the same authorization as a human WebUI action, so an Owner/Admin can submit sensitive Entity operations while a Member receives 403.

## Which layer to use

- A desired state, durable problem, or reusable decision policy → **Concept proposal**
- The concrete things that make up the company and where to focus improvement → **Entity**

Company context is both an input and an output of agent work. An agent working in a project returns findings as Concept proposals; once a human accepts them, every later session works on top of those criteria. This is how the company itself grows as an asset (the company-level version of the company assets flow in [concepts](/en/docs/concepts)).

## Entity model — kind, sensitive boundary, hierarchy

An Entity is an identifiable, persistent thing that concretely makes up the company. Entities form the Company map: they make it explicit what to build, improve, maintain, or retire, decomposed to a level where each improvement target can be selected independently.

**Entity stores no properties, evaluations, goals, KPIs, owners, or progress.** Those belong to Concept (decision criteria), Project/Session (work in progress), and Message/Shared Document (evidence and detail).

### What should be an Entity

Register something as an Entity when building, improving, maintaining, or retiring it can be decided independently. Create a child Entity only when separating it lets the company select that improvement target independently.

Before registering a new Entity, check existing Entities and add one only when the existing Entity is too broad as an improvement target. Goals, work, abstract responsibility areas, feature classifications, and implementation parts such as UI, APIs, Workers, CLI commands, or database tables are not Entities unless they are themselves concrete parts of the company that are improved independently.

### kind — 9 types

| kind | Note |
|---|---|
| `organization` | Normal |
| `offering` | Normal. A product or service |
| `media` | Normal. A channel or medium |
| `community` | Normal |
| `system` | Normal. An internal or external system |
| `facility` | Normal |
| `person` | **sensitive** |
| `partner` | **sensitive** |
| `agreement` | **sensitive** |

### The sensitive-kind boundary (important)

The three kinds `person` / `partner` / `agreement` **cannot be registered or changed by an agent**. If an agent attempts to register one, rename it, change its status, move it, or link a Concept to it, the server rejects the request. The rejection message is returned in Japanese regardless of the agent's own language:

> person / partner / agreement Entity の変更は human の操作が必要です。Project の human member に依頼してください。
>
> ("Changing a person / partner / agreement Entity requires a human action. Ask a human member of the project.")

Agents **can read** sensitive kinds — their name and structure are visible as part of the Company map. Writes are restricted to **human team Owners / Admins**; a regular human member is rejected as well. Don't infer an Entity's meaning or evaluation from what you read — only name, kind, status, and parent are stored.

### status — position in the company structure

`planned` / `current` / `retired` describe only the Entity's position in the company structure, not the progress of a piece of work.

- `planned`: planned as part of the company structure
- `current`: currently part of the company structure
- `retired`: no longer part of the company structure

**Hierarchy constraint**: an active Entity (`planned` / `current`) cannot be placed under a retired parent. Before retiring an Entity, its active children must be moved or retired first.

### Hierarchy (parent/child)

Entities form a tree. A parent is at most one Entity in the same team; self-reference, cycles, and cross-team parents are never allowed. Reparenting is done with a move operation. Don't represent more than one kind of structural relationship through parent (don't encode undefined relationships such as dependency, provision, or ownership into hierarchy or name).

### Concept link

An Entity can link to a published Concept with `realizes`. This is the only relation type in v1. Don't link to an archived Concept or one with no published content.

### Change history

Entity changes are recorded as append-only events: `registered`, `renamed`, `status_changed`, `moved`, `concept_link_added`, `concept_link_removed`.

## Register your first Entity

Open Entity in the Team sidebar and inspect the Entity map and existing names. A customer help center operated over time is a candidate for `media`; the work to launch it belongs in a Project. This example uses a Session agent. Replace `acme` with your Team slug and `acme/help-center` with a Project where the Session has collaborator/admin membership and coverage. Do not overwrite an existing file with the same name.

1. Run `chat registry refresh --all`, then read `aachat/teams/acme/entities/_index.yaml`. Follow its `file` references to the individual records you need.
2. If the Entity does not exist, save this complete file as `aachat/teams/acme/entities/help-center.entity.yaml`.

```yaml
format: aachat.team-entity/v1
id: null
name: Help center
kind: media
status: planned
parent: null
realizes: []
```

3. From the workspace root, check syntax, inspect the operation, and submit it.

```sh
chat registry check aachat/teams/acme/entities/help-center.entity.yaml
chat registry plan aachat/teams/acme/entities/help-center.entity.yaml --project acme/help-center
chat registry submit aachat/teams/acme/entities/help-center.entity.yaml --project acme/help-center
chat registry refresh --all
```

`check` validates locally. Confirm that `plan` describes a single registration before running `submit`. After a successful write, you can read the current Entity with its server-assigned ID and see it in Entity. Use the file referenced by the index thereafter; preserve its assigned ID and path. Registering a `planned` Entity is not evidence that the service has launched.

### Change a parent or connect a Concept

Refresh the existing `help-center.entity.yaml`, then change only `parent` to a relative reference to a real parent in the same directory, for example `parent: "./customer-services.entity.yaml"`. Repeat check → plan → submit → refresh, confirm the plan contains only a move, and inspect the new hierarchy in the UI. Use `parent: null` to return it to the root. Submit name or status changes separately from a move.

To connect a Concept, first locate its published file, then add one reference such as `"../concepts/customer-self-service.concept.yaml"` to `realizes`. Submit this operation separately too. These filenames are examples: copy actual filenames from the index. An Entity's `kind` is not an editable field after registration.

## Actors and permissions

| Operation | Session agent | Human Team Member | Human Owner / Admin |
|---|---|---|---|
| Register or change an ordinary Entity | With Project write permission and coverage | Allowed | Allowed |
| Change a sensitive Entity | Not allowed | Not allowed | Allowed |
| Propose a Concept, revision, or link | Proposal only | Proposal only | Propose and decide |
| Publish / decline a Concept, decide on links | Not allowed | Not allowed | Allowed |

When working as a human from a connected repo, first check that the Team projection is healthy in `aachat status`. Replace the commands in the Entity example with these. This CLI resolves the Team from the connection and file; it does not accept `--project`, `--team`, or `--via`.

```sh
aachat registry check aachat/teams/acme/entities/help-center.entity.yaml
aachat registry plan aachat/teams/acme/entities/help-center.entity.yaml
aachat registry submit aachat/teams/acme/entities/help-center.entity.yaml
aachat registry refresh --all
```

An outside agent using this CLI acts with the signed-in human's Team role. That is distinct from Session agent authority. A successful local plan does not guarantee server authorization.

## Where Registry and Meeting records live

Registry has two indexes: `concepts/_index.yaml` and `entities/_index.yaml`. Concepts describe decision criteria; Entities describe the things that make up the company. A [Meeting](/en/docs/meetings) records discussion, decisions, and follow-ups in Markdown; it is not a third registry. Keep Project work products in [Shared Documents](/en/docs/shared-documents).

A Session receives Meetings under `aachat/meetings/` as a read-only snapshot taken at startup. Registry YAML submission cannot create or correct them. Save Team-wide discussion as a Meeting; when part of it should become a reusable decision criterion, organize its evidence and propose a Concept.

## When a change does not apply

- `mixed_edit` means that one file combines multiple operations. Preserve your draft and split it into changes such as name only or parent only.
- For a sensitive-kind rejection, ask a human Project member to involve a Team Owner/Admin. Agent credentials cannot bypass this boundary.
- For a retired-parent or active-child error, change the order of moves and retirements to satisfy the hierarchy rules above.
- For stale state or an unknown result, follow [Registry recovery](/en/docs/concept-registry). Deleting YAML does not delete an Entity. Use `retired` to record that it is no longer part of the company.

Do not commit generated `aachat/teams/` or `aachat/.state/` into the workspace repository. Saving a file alone does not write to the server.

## Related pages

- Concept's types and lifecycle: [concept-registry](/en/docs/concept-registry)
- Projects and work context: [projects](/en/docs/projects)
- The WebUI as a whole: [webui](/en/docs/webui)
- Terms: [glossary](/en/docs/glossary)


---

# Concept Registry — types and lifecycle of decision criteria

> Propose Concepts with evidence and adopt decision criteria through human review. Follow YAML examples, semantic fields, revisions, sources, links, and recovery.

# Concept Registry — types and lifecycle of decision criteria

Of the two registries in [Company](/en/docs/company), Concepts hold reusable team decision criteria. This guide explains how to propose a criterion with evidence, have a human review and publish it, and use it after adoption. Session agents read projected YAML under `aachat/teams/<team>/concepts/`, edit it, and propose changes with `chat registry`.

## kind — Vision, Issue, and Policy

A Concept has one of three kinds. Choose it by the question the Concept answers. kind describes the content's role only; the semantic axes below (guidance_strength, etc.) are never derived automatically from kind.

| kind | Question it answers | Use |
|---|---|---|
| `vision` | What state do we want to realize? | A future or state the company wants to realize |
| `issue` | What currently prevents the Vision? | An important problem or gap the company must keep recognizing. Keep one-Project tasks and bugs in that Project |
| `policy` | What do we prioritize when making this kind of decision? | A reusable decision or action policy for moving toward a Vision and addressing Issues |

## Semantic axes — 6 axes

A Concept has 6 semantic axes independent of kind. YAML for a new Concept requires `scope` (domain + tags), `abstraction_level`, `time_horizon`, `guidance_strength`, and `maturity`. There is no automatic mapping such as `policy = governing`, and none is inferred from review counts either.

| Axis | Values | Meaning |
|---|---|---|
| **guidance_strength** (how strongly it directs judgment) | `contextual` / `guiding` / `governing` | `governing` is used as a standard premise; deviating from it requires a reason. `guiding` should be followed in principle but can be overridden with a reason given stronger evidence or a conflicting governing Concept. `contextual` is used as input only when relevant |
| **maturity** (how settled the revision is) | `exploratory` / `provisional` / `established` | `established` can be taken as a premise without re-examination. `provisional` should have its sources or latest reviews checked for high-impact decisions. `exploratory` may be included in published context but must not be restated as settled fact |
| **abstraction_level** (scope of impact) | `foundational` / `directional` / `structural` / `tactical` / `operational` | Chosen by the scope of judgment it affects, never inferred from kind |
| **time_horizon** (time frame) | `today` / `one_week` / `one_month` / `three_months` / `one_year` / `three_years` / `ten_years` / `enduring` | Every value except `enduring` requires an `expires_at`. After expiry, the Concept is excluded from current published context |
| **domain** (area of applicability) | `company` / `organization` / `product` / `marketing` / `sales` | Choose the one broad area the Concept applies to. Team-internal classifications such as product, customer segment, or initiative go in `scope.tags` (up to 20) |
| **applicability** (validity) | `active` / `expired` | A derived state based on `expires_at` |

`governing + established` is a standard premise. `governing + provisional` must always be considered, checking sources or the latest review for high-impact decisions. `governing + exploratory` must always surface but must not be blindly followed. When governing Concepts conflict with each other, or an unresolved concern exists, don't pick a winner by score — read links, sources, and reviews and surface the unresolved conflict explicitly.

## Revision model

A Concept is an immutable stack of revisions. The current revision is never rewritten directly; every change is recorded as a new proposed revision.

- A revision's `status` is one of `pending` / `published` / `declined`
- **A Concept can have at most one pending revision at a time.** A new proposal cannot be submitted while one is already pending
- **Only humans (a team's Owner/Admin) can publish or decline.** Agents can only propose
- **A decline requires a reason.** The next session should read that reason and calibrate its criteria before deciding whether to re-propose
- Once created, a revision's content is immutable. Even changes to wording, sources, scope, or time horizon are recorded as a new revision

Title is capped at 80 characters and description at 300 — they are an entry point, not a summary; the detailed evidence is read through sources (below).

## Reviews

Both pending and published revisions can carry two kinds of review: `endorse` and `concern`. A `concern` requires a comment (an `endorse`'s comment is optional), and can be resolved with a resolution note. A published revision may still be read as a premise even with an open `concern`, but for decisions that depend heavily on that Concept, check the current revision's comments with `aachat_concept_reviews` and surface that the concern exists. Post a review with `aachat_concept_review`; projected `concepts/_index.yaml` carries only `open_concern_count`.

## Links between Concepts

Concepts connect to each other through 8 directional relation types.

| relation | Meaning |
|---|---|
| `realizes` | Realizes |
| `constrains` | Constrains |
| `addresses` | Addresses |
| `measures` | Measures |
| `supports` | Supports |
| `contradicts` | Contradicts |
| `refines` | Refines |
| `depends_on` | Depends on |

Links also have a lifecycle: `candidate` / `accepted` / `retired` / `rejected`. An agent can propose a link as a `candidate` by editing a Concept YAML link and running `chat registry submit`, but **it counts as a valid relationship for the Concept Map or for judgment only once accepted. Only humans (a team's Owner/Admin) can accept, reject, or retire a link.**

When a published Concept would mislead future decisions, an agent can send an archive proposal to the Review queue with `aachat_concept_removal_propose`. For an accepted Link, remove it from the Concept YAML and run `chat registry submit --reason` to propose retirement. The Map does not change until a human accepts it, and history remains as an archived Concept or retired Link.

## Similarity gate on proposal

`chat registry submit` for a new Concept automatically checks it against existing Concepts before registration. If a similar Concept is found, the proposal is not registered and `similar_found` is returned instead.

- **A similar `published` Concept** — a decision criterion already exists. Withdraw, or switch to a link proposal or a review if there's a relationship. If the evidence reveals a durable gap, consider an `issue` + a `contradicts` link
- **A similar `declined` Concept** — a human already rejected this. Read the decline reason (`status_reason`) and don't repeat the same proposal
- **A similar `pending` Concept** — someone else's revision proposal is awaiting review. Don't submit a duplicate
- A match against a `pending` or `declined` Concept the caller lacks permission to see returns no content or ID — only `hidden_match_count`
- Only when the proposal is genuinely something different, resubmit with the returned `proceed_token` to register it anyway

## Sources

A proposal is submitted with sources attached. There are 4 kinds.

| kind | What it points to |
|---|---|
| `shared_document` | A Shared Document |
| `session` | A session |
| `external` | An external URL |
| `human_decision` | A human decision (a note) |

For a Session agent proposal, at least one source must belong to the Project selected by `--project`; other Project sources must also be in the same Team and Session coverage. A source's availability is shown as one of `accessible` / `restricted` / `unavailable`; don't guess at the content of a `restricted` source. `unavailable` means the source cannot currently be resolved; check for deletion or changes such as Session coverage.

## Archive / restore

A Concept can be archived and restored. This is a WebUI/human-only operation and is not exposed as an agent-facing MCP tool. Don't create new links to an archived Concept or one with no published content.

## Free placement on the Concept Map

The WebUI's Concepts screen has a map view. A card's position (`free_position`) can be moved by a human, or by an agent editing Concept YAML and running `chat registry submit`. Placement is shared soft context: proximity between Concepts can be a hint worth considering, but when it conflicts with sources, typed links, or semantic fields, those take precedence. Don't assert a relationship that appears only in placement as fact — if it looks important, treat it as a candidate for a link proposal instead.

## Propose a Concept with evidence

Open Concepts in the Team sidebar and inspect existing Concepts and the Review queue. If the policy or a pending revision already exists, read it and its reviews before proposing a duplicate. Check the [Company permissions table](/en/docs/company) first. The following steps are for a Session agent with Project write permission and coverage.

This example assumes that the `acme/help-center` Project has `docs/research/support-friction.md`, recording evidence that users could not find answers and explaining the proposed improvement. Replace the Team/Project, document kind, and document ID with real ones, read that evidence, and adapt the proposal. Do not submit a fictional source unchanged.

Run `chat registry refresh --all` and read `concepts/_index.yaml`. Then save this complete new file as `aachat/teams/acme/concepts/customer-self-service.concept.yaml`.

```yaml
format: aachat.team-concept/v1
id: null
kind: policy
title: Make answers easy to find
description: Prefer clear, searchable help before adding support channels.
scope:
  domain: product
  tags:
    - support
abstraction_level: directional
time_horizon: enduring
expires_at: null
guidance_strength: guiding
maturity: provisional
position: null
sources:
  - kind: shared_document
    project: "acme/help-center"
    document_kind: research
    doc_id: support-friction
restricted_source_count: 0
links: []
```

`id: null` means a new registration. New Concepts require `position: null` and `links: []`; change position and links separately after publication. A time horizon other than `enduring` needs a future expiry as a quoted RFC3339 timestamp. Supply 1–20 sources; a new Concept has `restricted_source_count: 0`.

From the workspace root, run these commands in order.

```sh
chat registry check aachat/teams/acme/concepts/customer-self-service.concept.yaml
chat registry plan aachat/teams/acme/concepts/customer-self-service.concept.yaml --project acme/help-center
chat registry submit aachat/teams/acme/concepts/customer-self-service.concept.yaml --project acme/help-center
chat registry refresh --all
```

`check` validates local YAML; it does not guarantee that a source exists or that the server will authorize the operation. Confirm that `plan` contains the intended single operation. After `submit` accepts the proposal, a Team Owner/Admin reads its evidence and changes in the Concepts Review queue, then publishes it or declines with a reason. Acceptance of a submission is not adoption of its content.

Projected YAML represents published current content only. Do not resubmit because the file returns to its old content or a new pending proposal's text does not appear in the index. Check the receipt and Review queue. After human publication, refresh and confirm the current content matches the adopted revision.

### Separate revisions from position changes

For an existing Concept, refresh the file referenced by the index's `file` field. To improve its description, edit `description`, preserve its existing ID and other required fields, and repeat check → plan → submit. Changes to meaning, sources, or scope create a new pending revision. If a revision is already pending, check its review outcome first.

To change position only, replace `position: null` or the current position in the existing file with this block, leaving every other field unchanged. Do not save this fragment as the entire file.

```yaml
position:
  x: 240.0
  y: 120.0
```

Repeat check → plan → submit → refresh. A position-only change applies directly; it does not approve the Concept's meaning. Coordinates must be finite, with each axis between -1000000 and 1000000. Editing meaning and position together produces `mixed_edit`, so submit them separately.

### Propose as a human from a connected repo

Check that the Team projection is healthy in `aachat status`, then use these commands with the same YAML.

```sh
aachat registry check aachat/teams/acme/concepts/customer-self-service.concept.yaml
aachat registry plan aachat/teams/acme/concepts/customer-self-service.concept.yaml
aachat registry submit aachat/teams/acme/concepts/customer-self-service.concept.yaml
aachat registry refresh --all
```

This CLI has no `--project` or `--proceed-token`. The repo connection determines the Team; the server checks access to the Projects named in sources. Even an Owner/Admin's semantic submission is a proposal; publication is a separate decision. Clearing position to null is unsupported in the outside CLI. Removing an accepted Link also differs from an agent's retirement proposal: it is a human retirement operation requiring Owner/Admin and `--reason`.

## Follow sources and reviews

Open Sources from a Concept Map card's menu to follow its evidence. Open the card's detail to inspect current content, reviews, and History. Distinguish pending content in the Review queue from the currently published content. For example, if the policy above is published but has an open concern that some languages remain hard to search, do not restate it as proof that all users can help themselves.

`restricted` means you lack access to that source. Ask an authorized human to check the necessary evidence; do not infer its contents. For `unavailable`, the source cannot currently be resolved. Check for deletion or changed Session coverage and consider a revision with accessible evidence. The WebUI requires access to all sources before proposing a revision. In a Session agent YAML revision, preserve `restricted_source_count` and edit only visible sources. The server inherits restricted sources and checks the combined limit of 20. The index's `open_concern_count` does not explain concerns, so read the comments. Expiry excludes content from current decision context; it does not delete its adoption history.

Both the Concept source model and Registry YAML `sources` accept four kinds: `shared_document`, `session`, `external`, and `human_decision`. It does not accept `project_message`. Inspect omitted sources in the WebUI instead of reconstructing them in the projection. For Session agent proposals, `external` or `human_decision` sources alone do not satisfy the Project-source requirement.

## YAML constraints and recovery

Use UTF-8 and LF newlines, without unknown or duplicate keys, tabs, anchors, aliases, merge keys, or explicit tags. Preserve quoted UUIDs, timestamps, and file references. Use a meaningful lowercase ASCII slug and `id: null` for a new record; never rename an existing ID or assigned path. Do not edit generated `_index.yaml`. Each submit handles one file and one operation. Saving is not a server mutation, and deleting a file does not archive a Concept.

| Situation | Next action |
|---|---|
| `mixed_edit` | Separate meaning, position, and individual links; plan one operation at a time |
| `similar_found` | Read similar content and decline reasons. Only a Session agent that concludes this is a distinct proposal should add `--proceed-token` to the same submit |
| Stale state / OCC conflict | Preserve the local draft, fetch server current, and reapply the intended change. There is no automatic merge |
| `outcome_unknown` | Keep file bytes unchanged and rerun the exact submit command returned by the CLI. Do not start another submission until reconciliation finishes |
| Projection unavailable / revoked / stopped | Do not treat remaining files as current. Follow the reported blocker to restore the runtime or Team access |

For a similarity-gate retry, use the actual token returned by the command.

```sh
chat registry submit aachat/teams/acme/concepts/customer-self-service.concept.yaml --project acme/help-center --proceed-token '<returned-proceed-token>'
```

Only for a conflict, preserve any needed local draft elsewhere before explicitly discarding changes to the affected file.

```sh
chat registry refresh aachat/teams/acme/concepts/customer-self-service.concept.yaml --discard-local
```

This discards local edits. Read current content, reapply only the intended differences, then repeat check → plan → submit. In a connected repo, replace `chat` with `aachat`. An ordinary refresh does not silently overwrite dirty files. For an unknown-result retry, the CLI uses retained inflight information to reconcile server state first; do not edit or delete that file or internal state.

## Related pages

- The two-layer overview and how to ask: [company](/en/docs/company)
- Entity's types and lifecycle: [company](/en/docs/company)
- Terms: [glossary](/en/docs/glossary)


---

# Shared Documents — source of truth and projection, the document contract

> The source of truth for Shared Documents is the server; local is a projection. Full-path WikiLink rules, kind and _template.md, the distinction between warnings and save rejection, and how edit conflicts are handled. Answer questions about the document contract from this page.

# Shared Documents — source of truth and projection, the document contract

Shared Documents are the "source of truth that does not scroll away," where agents and humans leave deliverables and decision material. While timeline messages flow past in chronological order, Shared Documents is where settled content is placed and where the next agent and human re-read it as "the truth."

The norm for choosing where things go is this: **put settled content — decisions, completed specs, and long-lived deliverables — in Shared Documents, and keep content still under consideration in chat / sessions.** A handoff remains in the session transcript; use a message for a short project-wide notice, or a normal Shared Document when it is substantial and independently worth rereading. Also, do not write questions to humans in document frontmatter; session agents use Project Asks ([Projects](/en/docs/projects)), and outside agents use their host ask.

## The relationship between source of truth and projection

**The source of truth for Shared Documents is on the server.** The local `aachat/projects/` directory is a projection, and syncs bidirectionally with the server only while `aachat up` is running.

- Editing local files syncs automatically. There is no manual sync command
- Local edits made while `aachat up` is not running are not synced; they re-sync while it is running
- If asked which side is authoritative: the server is the source of truth, local is the projection

The full picture of this boundary (what is stored on the server and what stays local) has its source of truth in [trust-boundary](/en/docs/trust-boundary).

## Document location and WikiLink

The accepted document paths are:

```
aachat/projects/<team>/<project>/docs/PROJECT.md
aachat/projects/<team>/<project>/docs/REPORT.md
aachat/projects/<team>/<project>/docs/<id>.md
aachat/projects/<team>/<project>/docs/<kind>/<id>.md
```

- `PROJECT.md` is the on-demand, read-first Project Contract / Context Router
- A root `<id>.md` is a root document without a kind
- `<kind>/<id>.md` is a document under a folder / kind
- `docs/index.md` is the automatically generated, exhaustive catalog of all documents; do not edit it

Create Document in the WebUI can target root, an existing folder, or a new folder. A folder with `_template.md` acts as a kind with schema and scaffold; without one it remains a raw Markdown folder.

### `PROJECT.md` is the stable Project Contract

Agents read `PROJECT.md` first only when a task needs project context. Keep it limited to stable information:

- Purpose
- Outcome
- Outputs
- Decision principles and boundaries
- A curated Context Map pointing only to important canonical sources
- A stable Approach

Do not put progress, assignments, handoffs, logs, or unresolved notes in it. The Context Map is a curated reading route, not a document inventory. Use generated `docs/index.md` when you need to discover documents outside that route.

### `REPORT.md` records results and remaining gaps

`PROJECT.md` defines the stable goal and acceptance conditions; `REPORT.md` records results, verified evidence, remaining gaps, and next steps. **Only the current Project Lead can create, update, or delete it.** Its exact path is `aachat/projects/<team>/<project>/docs/REPORT.md`. Do not substitute `report.md`, `Report.md`, or a document under a kind folder.

In the WebUI, find the REPORT by its title in the Project's **Docs** and open its body. If missing or outdated, ask the current Lead to update it. The Lead's normal file edit uses existing automatic sync; no manual sync or REPORT-specific command is needed. If it does not appear, see [sync recovery](/en/docs/troubleshooting).

An active Project with a Lead needs a REPORT to complete, but its presence does not automatically establish goal attainment. Review its content and deliverables using [the Project acceptance and Done procedure](/en/docs/projects).

### Connect documents with WikiLinks

Documents can cross-reference each other with WikiLinks. **A WikiLink is only the full-path form — the in-repository path wrapped as-is in `[[ ]]`; shorthand forms are errors and the save is rejected.**

```text
[[aachat/projects/<team>/<project>/docs/<kind>/<id>.md]]
```

In the WebUI, WikiLinks in document bodies and messages appear as document chips. A person or agent can read the body through the chip or full path when the target exists and they have access. Adding a WikiLink to a request does not create its target or grant permission to read it. See [Markdown blocks](/en/docs/markdown-blocks) for unresolved references.

The document panel's **Referenced by** list shows registered references whose source Projects the viewer can access. References through body WikiLinks and fields such as `depends_on` appear as chips, with badges identifying the fields. When references are registered and access conditions for each document are met, you can navigate in both directions, such as between a spec and related tasks.

### Check saving, reference registration, and reading separately

**A successful save does not guarantee that a linked document exists, that you can read it, or that the source appears in Referenced by.** On server versions that separate saving from reference registration, a body containing correctly formed full-path WikiLinks can be saved even when a target Team or Project cannot be found or is outside the saving person or agent's access scope. Check separately whether your environment has received a supporting version.

Reference registration checks for a non-deleted Team, an active Project, and an active Project membership for the saving person or agent. When a body mixes references that meet these conditions with references that do not, the body is retained and only the qualifying references are registered. However, registration does not check whether the target document itself exists. Even a registered reference still requires the target document to exist and the reader to have access when opening it.

After saving, first reopen the source document and check its body. Next, check whether you can open the target, and separately check whether its **Referenced by** list shows the source. If the target cannot be opened, check the full path, the target's existence, and the reading person or agent's permissions. Creating the Project or document later, or changing permissions, does not guarantee that an unregistered reference will be restored automatically.

This behavior does not change shorthand rejection or authorization to write the source. Saving still requires the source Project's state, editing permissions, Session coverage, and other save conditions to allow it. Distinguish unresolved references from the input warnings and save rejections described below.

## kind and `_template.md`

kind is the document's type (`spec` / `research` / `meeting`, etc.). **A kind is defined by placing `_template.md` in that kind's folder.** Write metadata in the `_aachat:` block at the head of the frontmatter; the rest of the frontmatter and the body become the scaffold for new documents.

```yaml
---
_aachat:
  schema:
    type: object
    required: [title, summary, status]
    properties:
      title:   { type: string, minLength: 1, maxLength: 120 }
      summary: { type: string, minLength: 1, maxLength: 400 }
      status:
        type: string
        enum: [draft, approved, published]
title: ""
summary: ""
status: draft
---
## Context
```

Only the following three keys can be written under `_aachat`; any other key is an error.

| Key | Required | Content |
|---|---|---|
| `schema` | ○ | Validation rules for the frontmatter (a subset of JSON Schema) |
| `template_policy` | − | The scaffold overwrite policy. `always_overwrite` (the default when omitted; distributed scaffolds are overwritten every time the template is updated) or `create_once` (created only the first time, never overwritten afterward) |
| `preview_fields` | − | An array of field names for the activity / document list API compact preview. Not used by the WebUI main timeline |

**An undefined kind is treated as plain Markdown.** Documents work normally without defining a kind; schema validation and scaffolds apply only to defined kinds.

Ready-made sets of kind definitions can be installed into a project from Discover's "Templates" (if a name collides with an existing kind, you can choose to overwrite after confirmation). The CLI covers the full set of operations with `aachat template list|search|show|install|publish|update|unpublish`, and kind definitions grown in your own project can be published to Discover with `aachat template publish`.

### Kind Definition in Project Settings

A Collaborator or higher in an active project can use **Kind Definition** in Project Settings to Install / Reload / Save / Delete raw YAML definitions and Publish them as Discover templates. When another change wins the save race, reload the latest definition, integrate the difference, and save again.

Deleting a Kind Definition does not delete existing documents. It removes the schema and scaffold, and documents in that folder fall back to raw Markdown. Confirm the validation and new-document scaffold that will be lost before deleting.

## The distinction between warnings and save rejection

Document problems fall into two tiers: "warning (the save goes through)" and "rejection (nothing is saved)." Do not conflate the two when answering.

**Warning (non-blocking)**: even if the frontmatter does not match the kind's schema, the save is not rejected. The mismatch is recorded as a warning and shown in the "Validation warnings" banner on the document panel. The design lets a human fix it later without stopping the agent's work.

**Rejection (not saved)**: common input-related save rejections include the following. Access restrictions, Project state, reserved paths, and revision conflicts can also prevent saving.

- kind name naming-rule violations (must start with a lowercase letter; allowed characters are lowercase letters, digits, `_`, and `-`; up to 32 characters; may not start with `_`)
- doc id exceeding the length limit (up to 64 characters)
- Syntax errors in the frontmatter itself
- Shorthand WikiLinks
- Exceeding 1 MiB per document

When working with local files, rejection and warning details are written out to `_errors.md` in each kind's folder. This is an auto-generated report file: do not edit it by hand; fix the reported cause and save again. When the problem is resolved, the content disappears as well.

## Editing in the WebUI and conflict detection

Documents can be edited from the WebUI's document panel. If another member or agent saves the same file first while you are editing, a "changed elsewhere" alert appears and you can choose among the following three options while keeping your draft.

| Button | Behavior |
|---|---|
| Reload latest | Reload the latest content (your edits are discarded) |
| Keep my draft | Keep your draft and continue editing |
| Overwrite with my draft | Save, overwriting with your draft |

Overwrite replaces the other writer’s changes. Preserve any needed draft separately and compare it with the latest content before choosing it.

## Discovery surfaces — Documents / WikiLink / project read

Creating or updating a document does **not** place it on the WebUI main timeline. Human discovery surfaces are:

- **Documents** (`/docs`): the in-project document index
- **document view / DocPanel**: the body surface opened from a path or WikiLink. Shows `title` / `summary` / `status`, frontmatter, and schema warnings
- **a short project message with a WikiLink**: a notification or short handoff when a human needs to notice a document change

Agents discover documents via the docs projection and CLI `aachat project read` (which still includes document create/update items). `preview_fields` is for the activity / document list API compact preview; when unspecified, whichever of aachat's default field set — `assignee` / `owner` / `priority` / `due_date` / `tags` / `depends_on`, etc. — exist in the frontmatter are used.

Document bodies can also contain ` ```mindmap ` blocks, displayed as a collapsible tree in the WebUI. A mindmap is a working surface for thinking, not the source of truth itself, so once direction is settled, have it compressed into normal body text centered on Decision / Next.

## Save your first deliverable

In an active Project, a Collaborator or Admin can create or edit ordinary documents; a Session agent also needs coverage of that Project. A Viewer can read, but cannot save. `REPORT.md` retains the Lead-only rule above.

In **Docs → Create Document**, choose a folder such as `research` and ID `customer-findings`. Alternatively, have the covered Session agent save `aachat/projects/acme/customer-research/docs/research/customer-findings.md`. Replace the example Project and `analyst.owner` with real names. A plain folder needs no kind definition to get started:
```markdown
---
title: Customer research findings
summary: Findings from the completed customer interviews.
status: draft
owner: analyst.owner
due_date: "2026-09-10"
tags: [research, customers]
related:
  - aachat/projects/acme/customer-research/docs/PROJECT.md
---

# Findings

Customers need a clear delivery date before ordering.

## Evidence

The interview notes support this finding. Separate observations from assumptions.

## Next action

Confirm the proposed delivery-date wording with the project owner.
```

Save, then reopen the document from Docs and confirm its title, metadata, and body. A local file alone is not proof of server acceptance. The document does not automatically appear as a new timeline message. If a notification is needed, share its full WikiLink in a Project message.

For a local preflight, run:

```sh
aachat doc check aachat/projects/acme/customer-research/docs/research/customer-findings.md
```

This checks the projected document's local input; it does not save it or prove that server sync or authorization succeeded. Read generated `_errors.md` diagnostics, repair the source, and reopen the accepted server document. Do not edit generated diagnostics. When sync is unavailable, keep your local work and follow [sync recovery](/en/docs/troubleshooting).

## Frontmatter that readers can use

Frontmatter is YAML data, not Markdown body. Use a plain full document path in `related` as above. If you put a `[[...]]` WikiLink in a YAML value, quote the entire value. Date strings should use ISO format. Metadata describes the document; an `owner`, `due_date`, or `commands` field does not itself assign work, schedule a Session, or run a command.

| Field | Value | Display |
|---|---|---|
| `title`, `summary` | String | Document heading and description |
| `state`, `status`, `priority`, `severity` | String | Badge; schema-defined status can offer selection |
| `owner`, `assignee`, `reviewers` | Member name or list of names | Member display |
| `due_date`, `deadline`, `*_at`, `*_date` | ISO date string | Date display |
| `tags`, `labels`, `categories` | Array | Chips |
| `related`, `depends_on`, `blocks`, `parent` | Full document path or array | Document links |
| `commands`, `pre_commands`, `post_commands` | String or array | Command chips |
| `*url`, `*link`, `*homepage` | HTTP(S) URL | Clickable URL |

Other fields fall back to their runtime value type. Naming does not override validation or permissions.

## Naming and schema reference

Ordinary document IDs match `^[a-z0-9][a-z0-9_-]*$` and are at most 64 characters. Kind names match `^[a-z][a-z0-9_-]*$` and are at most 32. Use only one kind directory: deeper nesting, `.`/`..`, backslashes, and a literal `root/` folder are not document identities. Reserve uppercase `PROJECT.md` and `REPORT.md` for their roles. `docs/index.md`, `_template.md`, and generated diagnostics are not ordinary deliverables.

Kind schemas support `type`, `properties`, `required`, boolean `additionalProperties`, `enum` with string/number values, `pattern`, `minLength`, `maxLength`, `minItems`, `maxItems`, `minimum`, `maximum`, object `items`, and `format`. `format` is an unchecked assertion, not a date or URL guarantee; unknown names can warn. Do not paste an arbitrary JSON Schema with `$ref` or composition keywords. Schema-definition errors differ from nonblocking warnings on a document's field values.

## Share the saved result

Use the document's public-link button only after checking the current body and referenced media. A single-document token reads the latest version of that document. An AI context token has much broader Project scope. See [Sharing](/en/docs/sharing) for creation, 7-day UI expiry, who can revoke, and why an existing URL cannot be copied again.

## Related pages

- Where Shared Documents sit among the concepts, and the two-layer context structure — [concepts](/en/docs/concepts)
- The full picture of the server/local boundary (including source of truth and projection) — [trust-boundary](/en/docs/trust-boundary)
- Project surfaces such as the timeline and Asks — [Projects](/en/docs/projects)
- WebUI screens and operations — [WebUI](/en/docs/webui)
- CLI command details — [CLI](/en/docs/cli)


---

# Markdown rendering and structured blocks

> Syntax and rendering for ordinary Markdown, Mermaid, code, Media, WikiLinks, mindmap and brainstorm. Compare chat, shared documents, public guides, and shared Markdown, with read-only operations and error recovery.

# Markdown rendering and structured blocks

aachat Markdown has two structured fenced blocks in addition to Mermaid: **mindmap** (organizing thinking) and **brainstorm** (diverging on options). Both can be written in chat messages and in shared document bodies, and the WebUI renders them as interactive cards.

Facts common to both:

- **The rendering is read-only.** Collapsing, sorting, and copying are available, but there is no UI operation that changes the content (rating, etc.). Updates are made by editing the Markdown body
- Writing a block **does not execute anything automatically**
- A syntax error turns the entire block into an error display (with line numbers), and the original text is shown as-is
- Both are working surfaces for thinking and coordination, not the source of truth. Compress settled conclusions into ordinary documents and request text

## Before writing — rendering and execution

Use Markdown to put prose, tables, diagrams, and artifact references in one body that readers can inspect. A person or agent who can post to chat, or edit the target shared document, writes the Markdown. Permission to view content is separate from permission to change it. See [Shared Documents](/en/docs/shared-documents) for saving and editing, and [Project Media](/en/docs/media) for preparing media.

**Displaying code, Mermaid, or a structured block does not execute its contents as commands, start a Session, or delegate work to the named agent.** `[Agent]` describes an assignment; it does not grant authority. Checkboxes, ratings, and statuses display values written in the body. Send work separately as a [Session request](/en/docs/sessions).

Rendering can still draw diagrams and fetch authorized Media. Opening a link can access an external destination. “No automatic execution” does not mean no network traffic. Pasting raw HTML is not a way to execute arbitrary HTML or scripts in these Markdown views. HTML artifacts follow the separate execution and sharing conditions of [Project HTML](/en/docs/html).

## Rendering and read-only operations

Here, chat means WebUI message bodies and shared documents means their WebUI Markdown preview. In the two block examples below, the outer four backticks let this guide display the syntax. To use a block, copy from the inner three opening backticks through the three closing backticks into your body. Numbers and plans in examples are illustrative, not measured results.

| Syntax | Display and reading operations in chat and shared documents | Errors, limits, and recovery |
|---|---|---|
| Ordinary Markdown | Headings, emphasis, quotes, lists, tables, links, strikethrough, and task lists. Open links and scroll wide tables horizontally | Clicking does not save checkbox state. Edit `- [ ]` / `- [x]` in the body. Include the separator row in tables |
| Ordinary code fence | Code display with language labels and copying. This is not a run-code button | An incorrect language name can prevent expected highlighting or custom rendering. Check the opening/closing fences and language name |
| `mermaid` | Renders a diagram, without an editor for its contents | Failure shows an error and the original code. Reduce to a small diagram and quote labels containing parentheses or pipes |
| Image `![description](URL)` | A Project Media canonical URL becomes an image when Project context and retrieval permission are available. Chat offers an enlarged preview; shared documents link to Media | External image URLs display as links without fetching the image automatically. Missing Project context gives an unresolved placeholder; retrieval failure offers retry. Check the URL, owning Project, and viewing permission |
| Video/PDF `[description](URL)` | Open the link to view it on the Media screen. This syntax does not create an inline video player or PDF viewer | Use ordinary links, not image syntax. Deleted or inaccessible Media cannot be opened |
| WikiLink `[[full path]]` | In a view with Project context, a document chip supports previewing or navigating to the document | Short or old paths show warnings; missing references appear unresolved. Check the real document path and permissions. Code contents are not converted into links |
| `mindmap` | Collapse the colored tree, highlight ancestors, and copy source | Unknown tags warn. Structural errors show line numbers and source text. Fix indentation, tags, and text |
| `brainstorm` | Cards, collapsing, a Sort toggle for display order, and source copying | Ratings are not editable. Invalid keys or values show line numbers and source text. Use the keys, lengths, and values below |

Chat and public guides display single source newlines as line breaks. Shared document previews treat single newlines as ordinary Markdown soft breaks within a paragraph. Use a blank line for a new paragraph, or two trailing spaces for an explicit hard break.

## Ordinary Markdown, code, and Mermaid examples

Paste this into a body to display a heading, emphasis, a quote, unchecked/checked items, a two-column table, and a guide link.

```markdown
## Review notes
Separate **conclusions** from *assumptions*. Strike out ~~old options~~.

> Check references before sharing.

- [ ] Check the diagram
- [x] Read the body

| Item | State |
|---|---|
| Draft | In review |

[Shared Documents guide](/en/docs/shared-documents)
```

The following code is displayed as text; it is not executed to print `hello`. Only if you want to run it, inspect its contents and execute it in a separate environment.

````markdown
```javascript
console.log("hello");
```
````

The following Mermaid produces a three-node “Draft → Review → Share” diagram. It explains a process; it does not perform sharing.

````markdown
```mermaid
flowchart LR
  A["Draft"] --> B["Check (review)"] --> C["Share"]
```
````

Mermaid renders with strict security settings. Do not rely on HTML or click-triggered script execution inside a diagram.

## Image, video, PDF, and WikiLink examples

First save Media and obtain its actual canonical URL from the Media list. The UUIDs below are examples: replace each with the UUID of your image, video, or PDF. Do not save short-lived delivery URLs or absolute local file paths.

```markdown
![Finished screen](https://aachat.io/m/11111111-1111-4111-8111-111111111111)
[Walkthrough video](https://aachat.io/m/22222222-2222-4222-8222-222222222222)
[Report PDF](https://aachat.io/m/33333333-3333-4333-8333-333333333333)

[[aachat/projects/example/demo/docs/notes/review.md]]
```

Replace the WikiLink with the full path of the document you want to reference, too. In a body it becomes a document chip; in this guide's code example it stays text. Writing a chip does not create the file or grant access to another Project.

## Public guides and shared destinations

| Content | Public guide HTML page (this site) | Public guide “Markdown” view | Public Markdown from a share link (`/share/…/*.md`) |
|---|---|---|---|
| Ordinary Markdown and code | Rendered prose and code | Markdown text | Markdown text, displayed according to the receiving tool's support |
| Mermaid and two structured blocks | Direct custom fences become diagrams/cards. Examples on this page stay code because of the outer fence | Fences and contents remain; no card UI | Fences and contents remain; aachat's card UI and validation display are not delivered |
| Images | Project Media is unresolved without Project context. External images become links | Authored image syntax and URLs | Tracked Media references in the shared surface are rewritten to token-scoped share routes. Media without a corresponding dependency becomes `Media unavailable` |
| Video and PDF | Ordinary links, subject to the destination's access rules | Authored links | Opening a shared Media link provides an image/video/PDF viewing page and original download |
| WikiLink | No document chip without Project context | WikiLink text | WikiLinks inside the body remain text, distinct from document and Session links generated around it |

The public guide's Markdown view is a way to read the article source, not a Project-sharing feature. Shared Markdown does not add a UI for editing document bodies or starting Sessions either. Diagram, HTML, and link handling in external Markdown tools depends on those tools, so keep the essential conclusions in ordinary prose as well.

Pasting a canonical Media URL alone does not give non-members access. Shared Markdown checks a valid share token and its scope; it does not unconditionally expose every referenced document or Media item. Some paths also turn external image references into links or text. If an expected image or document cannot be opened, its author should check the body reference, Media existence, share scope, expiration, and revocation. See [Shared Documents](/en/docs/shared-documents) and [Project Media](/en/docs/media) for those boundaries, and [Project HTML](/en/docs/html) for publishing a separate HTML artifact.

## mindmap — organizing the structure of an issue

Write `- [Tag] text` as a tree using space indentation. Use it to organize complex specifications, research, and decisions while distinguishing Fact from Assumption.

````markdown
```mindmap
title: Search improvement decision
- [Goal] Improve the first-run search experience
  - [Question] Where is it slow?
    - [Fact] p95 is 800ms; the index is unused
    - [Assumption] Users leave beyond 300ms
    - [Option] Add an index
      - [Risk] Writes get slower
    - [Decision] Validate adding the index first
      - [Next] Take a benchmark
```
````

- There are 12 tags: `Goal` `Question` `Fact` `Assumption` `Concept` `Cause` `Option` `Tradeoff` `Risk` `Test` `Decision` `Next`. Unknown tags are shown as-is with a warning
- The `title:` line is optional and can appear only once, before the first list item
- Indentation is spaces only (**tabs are an error**). Use `-` as the list marker. Maximum 200 nodes
- The rendering is a collapsible tree color-coded by semantic tag. Hovering highlights the ancestor path

## brainstorm — laying out options for evaluation

Write question / background / ideas in a YAML-like form. Use it to diverge on candidate specifications, UX, and improvements and have a human evaluate them.

````markdown
```brainstorm
question: How do we reduce onboarding drop-off?
background: |
  First-time setup completion is 60%. The drop happens just before agent creation.
ideas:
  - title: Create a template agent in 1 click
    description: |
      Clone a standard Discover agent with only a name input.
    rating: 4
  - title: Complete setup entirely in the WebUI
    description: Provide a path that defers the CLI install.
```
````

- The only root keys are `question` (required) / `background` (optional) / `ideas` (required). The only idea keys are `title` (required, up to 50 characters) / `description` (required, up to 200 characters) / `rating` (optional, integer 1–5)
- Both `background` and an idea's `description` support `|` multi-line text (up to 200 Unicode code points for the entire description). `question` and `title` are single-line. YAML features such as nesting and anchors are not available. Maximum 100 ideas
- The rendering is a grid of idea cards; rating appears as an `n/5` badge. **There is no feature to set or change a rating from the UI.** To reflect an evaluation, edit `rating:` in the Markdown body (the Sort toggle only changes display order)
- Do not leave important decisions sitting as a brainstorm; compress them into an Ask ([projects](/en/docs/projects)) or a specification document

## Repairing and redisplaying a block

Match the error line number to the original text inside the block, then edit the body, save, and view it again. Check for a missing closing fence, tabs, or unknown keys. Move long explanations into prose outside the block. Titles and items can use inline Markdown such as emphasis and links, but not block Markdown such as headings, quotes, lists, or another fence. Even when a warning allows rendering, correct the source instead of mistaking a mistyped tag for verified work. Readers without editing permission should ask the author to correct it.

## Related pages

- The practice of delegation and multi-agent collaboration: [sessions](/en/docs/sessions)
- Timeline rendering and WikiLinks: [projects](/en/docs/projects)
- The shared document contract (when writing blocks in documents): [shared-documents](/en/docs/shared-documents)


---

# Project Media — publishing finished images, videos, and PDFs

> The mechanism that publishes deliverables to a project by placing files in the media/ directory. States the supported formats, limits, canonical URLs, how media appears in the WebUI, and the boundary that session attachments (--attach) are not published.

# Project Media — publishing finished images, videos, and PDFs

Project Media is a server-side storage area for publishing and reusing **finished** images, videos, and PDFs as project assets. It is not a place for work-in-progress files. Published media appears in the WebUI's Media tab and can be referenced from the timeline, documents, and HTML through a stable URL.

## How to publish

There are two ways to publish.

1. **Place a file (the standard path for agents)**: put a finished file in `aachat/projects/<team>/<project>/media/` in the workspace, and it is detected and published to the server automatically. There is no dedicated command. The correct procedure is to create the file in a working directory and then move only the finished product into `media/` with `mv` (rename). Generating a file directly in `media/` while still writing it can get picked up in a half-finished state
2. **Upload from the WebUI**: the upload UI in the Media tab (humans only)

File placement detection follows these rules.

- `.tmp` / `.part` files, dotfiles, symbolic links, and directories are not published
- Deleting a file locally does not remove published media (it is not unpublished)
- Overwriting the same still-present path with identical bytes does not re-publish it. Reappearance after an observed deletion can create another publication

## Supported formats and limits

| Item | Value |
|---|---|
| Supported formats | Images (PNG / JPEG / WebP / GIF), video (MP4), PDF |
| Per image | Up to 20 MiB |
| Per PDF | Up to 50 MiB |
| Per video | Up to 2 GiB |
| Per project total | Up to 20 GiB |

Unsupported formats are rejected with `media_type_not_supported`; encrypted PDFs are also rejected.

## Referencing — canonical URL

The only stable reference to published media is the canonical URL `https://aachat.io/m/<uuid>`.

- Images can be embedded in Markdown as `![description](https://aachat.io/m/<uuid>)`. Videos and PDFs are placed as links
- Signed delivery URLs and storage URLs are short-lived and must not be saved in documents or messages. What you save is always `/m/<uuid>`
- The project's published list is available in the WebUI's Media tab, or with `chat media <project>` inside a session

The canonical URL is a stable **identifier**, not a public share URL. Resolving it requires authenticated membership in the active project that owns the media. Use an explicit share surface such as Project HTML when outside access is needed.

## Read existing Media inside a Session

A listing or canonical URL does not prove that a Session has read the image, video, or PDF itself. Download it with a supported CLI, then read the file identified by the success JSON. Do not fetch the canonical URL for bytes: it may return a login page.

### Check the prerequisites

Check the CLI inside the Session you will use:

```sh
chat --version
chat media --help
```

You need a CLI whose help includes `--download <MEDIA_ID>` and an API that supports Session Media delivery. The chat 5.7.26 installation checked on September 6, 2026 did not list download in its help. Syntax in source code or this guide does not mean it is available on your machine. If unsupported, stop here, retain the version and help output, and ask your administrator to confirm a supported version.

The target must be an active regular Project in the same team. The running Session needs coverage of that Project and write access (Collaborator/Admin). Being able to list Media alone does not establish eligibility for the delivery API. For authentication, permission, or API errors, follow the returned code and hint; do not bypass them by adding permissions or creating another Project.

### Select from the list, download, and read the file

1. Run `chat media <team>/<project>` to list ready Media and identify the target's `media.id` and canonical URL. Use `--q <text>` on the listing if needed. An empty list or missing target does not mean its contents have been checked. Check filters, pagination, the target Project, and readiness.
2. Replace the placeholders below with the actual Project and the UUID from the list. `<MEDIA_ID>` also accepts the exact canonical URL. Do not combine `--download` with `--q`, `--last`, or `--before`.

```sh
chat media <team>/<project> --download <MEDIA_ID>
```

3. Match `downloaded.media_id` in the success JSON to your target, then open the local file at `downloaded.path` with a reader that supports its format. The JSON also returns `content_type` and `byte_size`. Files go under the target Project's `media/.downloads/<id>.<ext>`, but use the returned path instead of guessing it from a name. Verify download success and content reading separately. If your reader cannot handle the file, its contents remain unverified.

The downloaded copy is for reading. Automatic publication skips `.downloads`; read the copy there without editing it or copying or moving it into the top level of `media/` to republish it. Keep the original canonical URL in documents and messages. Do not use a local path or a short-lived delivery URL as a shared link.

### When retrieval stops

| Result | Next action |
|---|---|
| `media_unavailable` | Check the same Project's ready list again. If the target is absent, check the Project, ID, and readiness, then retry once it is ready. Do not guess its contents. If needed, ask the human to attach the file to the Session |
| `media_download_failed` | Read the returned `reason` and retry once. If it fails again, report it with `chat report`. Without success JSON, do not treat the attempt as downloaded. A file from an earlier download may remain at the same path; its existence alone does not prove this attempt succeeded |

Include the Project and Media ID, time, CLI version, any known daemon/API versions, error and reason, and path state in the report. Mark unknown versions as unknown and omit credentials and signed URLs. See [CLI](/en/docs/cli) for syntax and [Troubleshooting](/en/docs/troubleshooting) for other symptoms.

## Detail, feedback, and deletion

Media detail provides preview and original download, metadata such as image dimensions or PDF page count, and publication history. When the media has a source session, you can send feedback on that deliverable or start a new session with the media as context.

Deleting server media is an irreversible operation available to members with write access (Collaborator/Admin) and to Sessions that cover the Project.

- A current Shared Document or Project HTML reference blocks deletion. Remove the reference and retry
- Historical or untracked references produce a warning. Inspect consumers before continuing
- After deletion, the canonical URL no longer resolves, including links stored in old messages or outside systems

Deleting the local file under `media/` does not delete already-published server media. Delete it explicitly from Media detail, or from a Session with `chat media <project> --delete <MEDIA_ID> --revision <N>`.

## The boundary that is not published — session attachments

Files passed with `--attach` on `session run` / `session send` **go only to Session history and are not published to Project Media**. `--attach` passes images as request context; placing files in `media/` publishes them as project assets. Do not conflate the two.

Note that Entity kinds also include a name called `media` ([Company](/en/docs/company)), but that is a separate concept representing a company's media outlets and channels.

## Publish and verify a finished report

Use an active Project and a publishing Session with Project coverage and write access (Collaborator/Admin). Keep `aachat up` running. First finish `./output/customer-report.pdf` outside the watched directory, then replace the example Project name and move the completed file:
```sh
mkdir -p aachat/projects/acme/customer-research/media
mv ./output/customer-report.pdf aachat/projects/acme/customer-research/media/customer-report.pdf
chat media acme/customer-research
```

The file is detected, uploaded, and processed before it becomes ready. Open **Media**, find the report, and inspect preview, metadata, and original download. Copy its actual canonical URL into the Shared Document; do not invent a UUID from the filename. A placement or upload receipt alone is not proof that processing succeeded.

Replacing the same local path with different finished bytes creates a new publication; inspect publication history and the returned media identity. Existing canonical asset links do not mean “whatever file is now at this local path.” Reusing an unchanged present file avoids duplicate publication; deletion and later reappearance are separate watcher state transitions. Do not use remove-and-replace as a server deletion operation.

If nothing appears, check that the file is complete, supported, within quota, not ignored or a symlink, and inside the correct covered Project. For a processing or failed item, read its status/error and fix the source or the reported condition before publishing again. If a document or HTML build cannot resolve an asset, check ready status and the exact canonical reference. If deletion is blocked, remove current document/HTML dependencies and wait for their accepted update/build; do not repeatedly request deletion against unchanged references.

For external readers, use [a Markdown or HTML share](/en/docs/sharing) that authorizes the relevant dependency. The canonical URL itself retains member access checks.

## Related pages

- The full picture of deliverable surfaces (docs / media / html / apps): [Projects](/en/docs/projects)
- Deliverables viewed in the browser: [HTML](/en/docs/html)
- The list of what is stored on the server: [Trust Boundary](/en/docs/trust-boundary)

Small files can still exceed image dimensions, animation frames, PDF page counts, or video duration. Check the [content limits as well as bytes](/en/docs/limits) before retrying; changing an extension does not change the format.


---

# Project HTML — browser-viewable deliverables and share links

> The mechanism that makes static HTML placed in the html/ directory viewable in the browser as-is. States the file layout rules, limits, member-facing Open HTML, and external-facing Share HTML (public URL, password, expiry).

# Project HTML — browser-viewable deliverables and share links

Project HTML is the mechanism that makes a set of static HTML files created by an agent viewable in the browser as-is. Use it to share prototypes, visual reports, and demos. Placing files in `aachat/projects/<team>/<project>/html/` in the workspace is all it takes to sync; there is no dedicated sync command. Creating, updating, and deleting files is ordinary file editing.

## File layout rules

- The entry point is `html/index.html`. When a project is created, a hub `index.html` (with Pages navigation) is generated automatically. For multi-page deliverables, add sibling `.html` files and link them from the hub; for a single report or app, replace `index.html` entirely
- Put CSS / JS / data files under `html/` as well and reference them with **relative paths**. A single file is not required
- The limits are **5 MiB per file / 500 files / 50 MiB per project total**
- Paths are relative only. A leading `/`, `..`, or a first segment of `__aachat`, `_aachat`, or `_media` is rejected; those names are reserved for Project HTML delivery and virtual endpoints
- Reference Media in the same project with the Project-root form `./media/<canonical-uri-path>`, or use an exact published canonical URL ([media](/en/docs/media)). This meaning is unchanged in nested HTML, CSS, JavaScript, and JSON files
- Encode each Media path segment as UTF-8 bytes, leaving only ASCII letters, digits, `-`, `.`, `_`, and `~` unescaped. Use uppercase `%HH` for every other byte, for example `素材/hero #1.png` becomes `./media/%E7%B4%A0%E6%9D%90/hero%20%231.png`
- Media references must be complete static tokens in UTF-8 `.html`, `.css`, `.js`, `.mjs`, or `.json` source. Exact tokens in comments, text, or unused code still declare dependencies
- Service Workers / Web Workers / Shared Workers are not available. Do not embed secrets or tokens in the HTML

Project HTML rejects embedding in iframes and other ancestors with `frame-ancestors 'none'` / `X-Frame-Options: DENY`. It also blocks device APIs such as camera, microphone, location, payment, and USB, Workers, and form submission from ordinary content. Content delivery accepts GET / HEAD only. The one exception is a narrowly scoped same-share-origin POST for the authentication form of a password-protected public share. Do not embed credentials in HTML; any network request runs with the viewer browser's authority.

Ordinary JavaScript in Project HTML is allowed and executes in each viewer's browser, including for member previews and public shares. The delivery CSP does not define `script-src` or `connect-src`, so scripts can initiate network requests under the viewer browser's rules. Review generated HTML before opening or sharing it, and never embed secrets or privileged credentials.

## Viewing HTML pages (for members)

The project HTML catalog separates browser pages from their supporting files:

- **Pages** lists each `.html` file by filename and path. Select a row to open that page in a new isolated tab
- **Assets** contains CSS, JavaScript, images, and other supporting files and stays collapsed until you need to inspect the file structure
- `Updated` is the last source update accepted by aachat, not the time the serving snapshot was published

Source sync and the serving-snapshot build are separate stages. Page rows become available only when the latest build is serving. An update becomes rebuild-pending and switches to the new snapshot only after a successful build. If rebuild fails, the previous healthy snapshot continues serving, but the catalog does not open it as though it contained the latest source. Inspect the HTML catalog status and error, fix the cause, and sync again.

Legacy `/_media/`, noncanonical encoding, and unresolved or not-ready Media make the latest build fail without rejecting source sync. Fix the diagnostic reference or publish the same path as ready Media. Never author `/_aachat/media/...`, dependency IDs, provider URLs, or signed URLs; those are delivery details generated for a ready snapshot.

## Sharing — Share HTML (external-facing public URL)

To show it to outside people with just a URL, issue a public URL with **Share HTML** on the project screen (Collaborator / Admin only).

- There is **only one public URL per project**. Enable it with "Enable and copy" and manage it with Copy / Extend / Password / Reset link / Stop sharing
- It has an expiry: **7 days by default, 30 days at maximum**. Extend it with Extend
- Password protection can be set optionally
- The URL is served from a sharing subdomain (of the form `h<key>.html.aachat.io`); Reset link (rotate) invalidates the old URL
- Agents cannot issue a public URL. The decision to publish and the operation are performed by humans

## Build a small report

Use an active Project and a Collaborator/Admin authoring role; the authoring Session must cover the Project. With `aachat up` running, save the following as `aachat/projects/acme/customer-research/html/report.html`, replacing the Project path with yours. Add its companion `html/report.css`. This example needs no backend or external script.
```html
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Customer research</title>
  <link rel="stylesheet" href="report.css">
</head>
<body>
  <main>
    <h1>Customer research</h1>
    <p>Customers need a clear delivery date before ordering.</p>
    <details><summary>Next action</summary>
      <p>Confirm the proposed wording with the project owner.</p>
    </details>
  </main>
</body>
</html>
```

`html/report.css`:

```css
body { margin: 0; font: 1rem/1.6 system-ui, sans-serif; color: #172033; }
main { max-width: 48rem; margin: auto; padding: 2rem; }
summary { cursor: pointer; font-weight: 600; }
```

Add `<a href="report.html">Customer research</a>` to the existing `html/index.html` hub without removing its other page links. For a single-report Project, you can instead save the report as `html/index.html`. CSS is relative to the HTML file: if you move the report into a subdirectory, adjust that relative path.

After sync and a successful latest build, open **HTML → Pages → report.html**. Expect the heading, a readable centered layout, and a Next action disclosure that expands when selected. A member can open the page without enabling a public share. To show a ready Media asset, use the canonical reference rules above; a local image filename is not proof it has been published.

Project HTML hosts static files. It does not start a server, provision a database connection, inject credentials, or grant a viewer the author's Project API permissions. Prepare a static data file if the report needs database results, and review that data before sharing.

## Check updates and sharing failures

If the page is missing, check the Project path, authoring permission, file limits, sync, and the catalog diagnostic. If it is pending, source acceptance has happened before a usable new build. If failed, fix the reported path or Media reference and save again; an older successful snapshot is not proof the new source is visible.

Share HTML exposes the Project's built HTML surface, not just the page you selected. Review all files, data, scripts, and media dependencies before enabling it. Later successful builds update what the share serves. If a public reader cannot open it, inspect expiry, password, reset/stop state, Project status, and latest build state. Reset link invalidates the old URL; Stop sharing disables public access, but neither retracts copies a recipient already saved. See [Sharing](/en/docs/sharing) to choose a narrower document link.

## Related pages

- The full picture of deliverable surfaces (docs / media / html): [projects](/en/docs/projects)
- Publishing images, videos, and PDFs: [media](/en/docs/media)
- Where the operations live in the WebUI: [webui](/en/docs/webui)


---

# environment.yaml — separating declaration, approval, and values

> The contract for declaring, approving, and resolving environment variables passed to local agent sessions.

# environment.yaml — separating declaration, approval, and values

`environment.yaml` at the agent repo root declares names for dependency packages and environment variables needed by a **local agent session**. Separation is the core design: only names and purposes in the repo, the value's resolution source only on the owner's local machine, approval explicitly per agent. aachat's provider-resolution and injection path does not copy the value to the server.

When asked where secrets live, answer with these three layers.

| Layer | Location | Content |
|---|---|---|
| Declaration | `environment.yaml` in the agent repo | Environment variable names and purposes only. **Writing values is rejected** |
| Approval | `~/aachat/.state/env.toml` on the owner's local machine | The list of names allowed to be passed, per agent (deny-by-default) |
| Value | provider (`~/aachat/.run/.env` or the Infisical CLI) | The actual values passed to local agent sessions |

Only names present in all three are passed when a new Session process starts. If any layer is missing, the value is simply not passed; startup itself is not blocked.

## Declaration: the environment.yaml contract

Declare environment variables under `config.env`.

```yaml
config:
  env:
    - name: OPENAI_API_KEY
      purpose: OpenAI API access
```

- Each entry may contain only `name` (required) and `purpose` (optional). Writing any other key such as `value` is **rejected with an error**. Because the agent repo may be cloned or published, value contamination is prevented structurally
- Names must match `[A-Z_][A-Z0-9_]*`. Names starting with `AA_` are reserved by aachat and cannot be declared. Duplicate declarations of the same name are an error
- A new Session process reads the **latest commit pushed** to the agent repo. Local edits alone do not take effect; changes apply from the next process spawn after pushing (same reflection rule as [agents](/en/docs/agents))

## Approval: deny-by-default in env.toml

A name that is merely declared is not passed. Only names the owner has **explicitly approved per agent** in `~/aachat/.state/env.toml` are passed to a session. Even if the repo side adds declarations on its own, unapproved names become `denied`.

Normally, do not edit this file directly. Run `aachat env` in a terminal. It safely initializes the default `run_env` configuration when needed, accepts missing values without echo, and then asks for per-Agent approval.

```toml
schema_version = 1
default_provider = "run_env"

[providers.run_env]
path = "~/aachat/.run/.env"

[agents."researcher.kensaku"]
env = ["OPENAI_API_KEY"]
```

- `schema_version` is fixed at `1`. `default_provider` is `"run_env"` or `"infisical"`
- Approval is per agent full name (`{base}.{owner}`). The same variable name requires separate approval for a different agent
- Do not write values in this file either. Unknown keys are an error

## Values: provider

Only **one** provider — the one chosen by `default_provider` — is used. There is no fallback or layering that combines both.

- **run_env** (default): `aachat env` safely appends missing values to the file at `providers.run_env.path` (default `~/aachat/.run/.env`)
- **infisical**: fetch from the Infisical CLI. aachat does not write values; add a missing value in Infisical and rerun `aachat env`

### Configuring Infisical

1. Install the `infisical` CLI and log in with `infisical login` (in CI and similar environments, the environment variable `INFISICAL_TOKEN` can authenticate instead; `INFISICAL_TOKEN` takes precedence over the login). `infisical init` and `.infisical.json` are not needed; the target project is specified explicitly in the configuration
2. Write `~/aachat/.state/env.toml` as follows

```toml
schema_version = 1
default_provider = "infisical"

[providers.infisical]
project_id = "<Infisical Project ID (UUID)>"
environment = "dev"   # Infisical-side environment slug
path = "/"            # Infisical-side secret folder path

[agents."researcher.kensaku"]
env = ["OPENAI_API_KEY"]
```

3. Place secrets with the approved names in the corresponding project / environment / path on the Infisical side

All three fields of `[providers.infisical]` (`project_id` / `environment` / `path`) are required; if any is missing, the agent's startup fails as a configuration error. Each new Session process preparation resolves the names declared and approved for that Agent once. An export failure becomes `provider_unavailable` with a bounded category such as `missing_executable`, `permission_denied`, `command_failed`, or `invalid_data`, and the Session starts without provider values.

### How to add approvals

Normal operation is covered by these commands:

```text
aachat env
aachat env list [--all]
aachat env approve <agent-full-handle> <NAME>
aachat env revoke <agent-full-handle> <NAME>
```

The command without arguments is TTY-only and never accepts a value through an argument or pipe. `list` shows unfulfilled requests, while `list --all` also shows `ready` and `no longer requested`. `approve` accepts only an exact currently declared name with a provider value; `revoke` removes only that Agent approval and leaves the value intact. Approval and revoke changes apply to newly started Session processes; they do not change the environment of a process that is already running.

## Verification and what failures mean

`aachat env list` shows only request states and actions, never values. Provider resolution happens during the actual Session prepare rather than during `aachat up`; an Agent log warning from that prepare is authoritative for `provider_unavailable`. Agent code receiving a value can still print or transmit it, so avoid commands that display secrets and minimize granted authority.

| Shown as | Meaning | Fix |
|---|---|---|
| `value missing` | Declared, but the provider has no value | Run `aachat env`; for Infisical, add it provider-side |
| `approval required` | Declared, but not approved for this Agent | Use `aachat env` or `aachat env approve` |
| `ready` | Declaration, approval, and value are present | Wait for the next process spawn |
| `no longer requested` | A local approval remains after the declaration was removed | Use `aachat env revoke` if desired |
| `provider_unavailable` | The provider itself could not be read; a bounded `provider_failure` category explains why | Follow the category action to check configuration, path or permissions, or the Infisical CLI / login |

If `environment.yaml` or an existing `env.toml` is invalid, Session prepare fails with a redacted error instead of spawning a process with an incorrect allowlist.

## networking.type and packages — declared only, not interpreted at runtime

The `environment.yaml` template has declaration fields for `config.networking.type` and `config.packages`, but **the only thing the runtime interprets at execution time is `config.env`**.

- **Network restriction is not implemented.** Writing `networking.type` does not restrict the agent's network destinations. To actually restrict them, use the sandbox / permission settings of the coding agent the agent runs on, such as Claude Code
- `packages` is likewise declaration only; the runtime performs no automatic installation

When explaining security to users, do not conflate the implemented mechanisms (non-duplication of values, deny-by-default approval) with the declaration-only fields (networking / packages).

## Relationship to the server

The provider-resolution and injection mechanism itself does not send or store session environment secret values on the server. After injection, the local agent runtime has no aachat-enforced destination restriction, so agent code can technically send a value to the server or elsewhere. External Session Run credentials have a separate server-side boundary. See [trust-boundary](/en/docs/trust-boundary) for the complete picture.

## Walk through a new secret request

For example, an Agent named `researcher.kensaku` needs `OPENAI_API_KEY` for a task. Replace the Agent handle with yours.

1. Add the names-only declaration shown above to the Agent repo, review it, and commit and push.
2. On the owner's runtime machine, run `aachat env list`. Use `aachat env` in a terminal to supply the missing provider value and approve the exact Agent/name pair. With Infisical, add the value in the configured provider location first.
3. Run `aachat env list --all` and confirm `ready` for the intended Agent. Do not print the value to test it.
4. Start a new Session process and perform a small authorized task that requires the value. Check its result and any redacted provider warning. `ready` proves configuration readiness, not successful authentication with the destination service.
5. When access is no longer needed, run `aachat env revoke researcher.kensaku OPENAI_API_KEY`. This removes this Agent's future injection approval and preserves the stored value. Already-running processes retain their environment; revoke or rotate the actual credential at its provider if access must end there as well.

Copying an Agent or Skill never copies local approvals and provider values. Prepare them on the machine and for the Agent that will actually run the new task. The [Setup authentication comparison](/en/docs/setup) separates these values from browser, CLI, Desktop, and external-start credentials.

## Related pages

- Agent repo structure and when changes take effect: [agents](/en/docs/agents)
- Full picture of the trust boundary (where secrets live, behavior during outages, implementation status of restrictions): [trust-boundary](/en/docs/trust-boundary)
- Setup including `aachat up`: [setup](/en/docs/setup)


---

# Connected repo — bringing Cursor / Claude Code into a project

> The mechanism for connecting a development repo to a team with `aachat init` so that external coding agents working in it can join projects. Write boundary, files placed, sender recording, and the facts of client entry for welcoming clients without a GitHub account.

# Connected repo — bringing Cursor / Claude Code into a project

Agents running under `aachat up` are not the only participants in aachat. When you connect a development repo to a team with `aachat init`, external coding agents such as Cursor / Claude Code working in that repo can operate the same surface as project members — messages, Shared Documents, session launching, and Asks. aachat does not replace these tools; it lets them participate (for the axis of comparison, see [concepts](/en/docs/concepts)).

A connected repository is optional. Codex and Claude Code first fetch and save the five public files linked from the [official aachat skill](https://aachat.io/orchestration-skill.md) in their user skill directory. The external agent then reads the saved skill and follows its setup instructions to download and install the aachat CLI with the official installer. Skill installation uses this same public download-and-save procedure even when the CLI is already installed. Agents can work with the common `AACHAT_HOME` (default `~/aachat`) projection using an explicit `--team`. The CLI installer and skill do not require a business-code repository or Team default repository; GitHub authentication and Agent repositories are still used.

This connection is a separate mechanism from the GitHub App integration configured in the WebUI team settings and from the agent's working repo setting. It is completed with only the local repo and the aachat CLI; no GitHub-side configuration is needed.

aachat has three mechanisms for "connecting a repo", and they are independent of each other. They are easy to confuse, so first establish which one is being discussed.

| Mechanism | How it is configured | What it is for |
|---|---|---|
| Connected repo (this page) | `aachat init` in the repo | Bringing external coding agents working in that repo into projects |
| workspace repo | project / team settings, `session run --repo` | Determining the repo checked out into a session's workspace ([sessions](/en/docs/sessions)) |
| Repository tree | The GitHub App integration in team settings | Showing a read-only file tree in the WebUI sidebar ([webui](/en/docs/webui)) |

## What external agents can do after connecting

| Goal | Operation |
|---|---|
| Report and share to a project | `aachat project send` (record the sender with `--via`) |
| Check new messages and mentions addressed to you | `aachat inbox` / `aachat mentions` |
| Delegate work to an agent on aachat | `aachat session run` / `aachat session send`. The target agent must be a member of the target project |
| Search past conversations | `aachat find` (cross-project message search) |
| Persist deliverables and specs as the source of truth | Edit Markdown under `aachat/projects/<team>/<project>/docs/` directly (synced as Shared Documents) |
| Ask a human for a decision or approval | Host ask in this conversation. Use `aachat ask list|show|answer|cancel` for existing project Asks |
| Place browser-checkable deliverables | Put static files under `aachat/projects/<team>/<project>/html/` |

External agents perform these by following the guidance of the placed skill (described below). The user only needs to make requests in natural language inside the editor.

Note that agents inside sessions started by `aachat up` use the dedicated `chat` CLI, not this surface. For in-session operations, see [cli](/en/docs/cli).

## What `aachat init` does

Prerequisite: setup is complete ([setup](/en/docs/setup)). Run it at the repo root.

```bash
aachat init
```

If you belong to multiple teams, a selection prompt appears. `aachat init --team <slug>` specifies the team directly. The command only creates or repairs the repo-to-team connection; it does not create, search for, or join projects. Use the project commands or WebUI when you want to work with a project.

`aachat init` is idempotent and safe to run any number of times. On an already-connected repo it repairs the existing connection files, so teammates can connect a cloned repo by running the same command.

Success check: `✓ Connected this repo to aachat` is displayed. Following the guidance, commit `aachat/README.md`, `.gitignore`, and the generated skill.

## Files placed

| Destination | Content |
|---|---|
| `aachat/README.md` | Connection manifest. Connected team information and usage rules for external agents |
| `.claude/skills/aachat/SKILL.md` and `.agents/skills/aachat/SKILL.md` | The same official aachat skill bundle for Claude Code and Codex / compatible agents. Each root includes `SKILL.md` and `references/{setup,operations,delegation,improvement}.md`, with the same canonical content served by public HTTP |
| `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.github/copilot-instructions.md` | aachat guidance appended as a managed block, only to files that already exist |
| `.gitignore` | Excludes `aachat/*` from git (with `!aachat/README.md` as the only exception) |
| `aachat/agents` | Symlink to `~/aachat/agents` (Unix / WSL only) |

## Write boundary

`aachat init` writes only to files inside the repo and to the local connection record in `~/aachat/.state/repo-connections/`. The following are rejected.

- Writes to paths outside the repo
- Writes to paths whose write path contains a symlink (the error instructs you to replace it with a real directory and rerun)
- Cases where `aachat/` already exists as something other than a directory (including a symlink)

Only the minimum information needed for the connection is sent to the server; the repo's contents are never stored on the server (for the full picture of the boundary, see [trust-boundary](/en/docs/trust-boundary)).

## Recording the sender — `--via`

When an external agent sends a message, it records which client it was sent from with `--via <label>`.

```bash
aachat project send <project> "Starting the research" --via cursor
```

The known labels are `cursor` and `claude-code`. Other clients may use any label. The recorded label is displayed next to the sender name in the WebUI Timeline, like `(cursor)`.

## Shared Documents sync requires `aachat up`

`aachat/projects/<team>/<project>/docs/` is a projection of the Shared Documents on the server, and it syncs bidirectionally only while `aachat up` is running locally. There is no dedicated sync command. Edits made while `aachat up` is stopped are not reflected, so when combining external agents with Shared Documents, keep `aachat up` running. The source of truth is the server side ([trust-boundary](/en/docs/trust-boundary); the document contract is [shared-documents](/en/docs/shared-documents)).

## Exploring messages, Team current state, and Meetings

External agents working in a connected repo search past messages across projects with `aachat find`. Agents inside sessions started by `aachat up` use `chat find`. Message search is not an `aachat-mcp` responsibility.

While `aachat up` is running, the connected repo receives the same Team current-state paths as a session: `aachat/teams/<team>/{concepts,entities}` plus the 50 most recent Meeting bodies under `aachat/meetings/`. Before company-context-dependent work, check `aachat status` and require `daemon.workspace_mirror.team_projection.state` to be `healthy`. When it is `unavailable`, `revoked`, or `stopped`, remaining files may be stale; follow the blocker instead of reading them as current.

Read the two Registry `_index.yaml` files first, open only the relevant individual YAML, then search Meeting bodies by the selected names. Individual Registry YAML is editable, but saving it only stages a local change. Validate and send one native operation with `aachat registry check / plan / submit`; clean files can be updated with `aachat registry refresh`. Indexes and Meeting Markdown are generated and read-only. Session agents use the same filesystem schema with `chat registry` and session authority. `aachat-mcp` still provides only the 3 tools for reading Concept reviews, posting a review, and proposing removal.

## Welcoming clients without a GitHub account — client entry

There is one more entry path from the outside besides coding agents: client entry, which welcomes a client for a specific engagement or an external collaborator into a dedicated project without requiring a GitHub account or any login step. You hand over a public URL to a single form; when the client submits it, a guest account and a dedicated project are created on the spot, and the conversation starts with the first message already posted.

Use it separately from team invitation links, which are for welcoming ongoing members. The client joins only the created dedicated project and cannot see the team's other projects.

### Configuration

Configure it in the Client Entry tab of Team Settings. Only the owner and Admins can operate it, and it is not available in personal teams. Configuration has two stages: a project template and a public entry link.

Project template (the blueprint for the project created when a client joins):

| Field | Content |
|---|---|
| Name | Administrative name of the template |
| Project name pattern | Pattern for the created project name. Can combine `{date}` / `{display_name_slug}` / `{short_id}` |
| Template enabled | When off, stops new project creation from this template |
| Default members | Team members who join automatically. They are added as project Admins. If empty, the link creator joins as Admin |
| Default agents | Agents that join automatically. They are added as Collaborators |

If a project with the same name already exists, a short ID is automatically appended and the collision is avoided.

The public entry link (the URL you hand to the client) is created with one template selected. Its fields are Title / Description / Expires at (omit for no expiry) / Message prompt / Enabled. **The public URL is displayed only once, at creation time.** If you forgot to save it or suspect a leak, reissue it with Rotate (the old URL becomes invalid). Multiple links can be created, and turning Enabled off stops new submissions only, leaving already-created projects intact.

### What the client experiences

1. Opening the public URL shows a form (Email / Display name / Message) that requires no login
2. Submitting it automatically creates a guest account. No GitHub account is needed
3. A project is created following the template's name pattern, and the client joins as a Collaborator. Default members join as Admins and Default agents as Collaborators at the same time
4. The entered Message is posted to the project as the client's message, and the project screen opens

### Guest account constraints

- The login state is stored in the browser that submitted the form and is valid for 7 days
- Guests have no password and no way to log in again. The client cannot return to the same project from another device, another browser, or after the 7 days
- If the same client submits the form again, a new separate guest account and a new project are created even with the same email address
- For engagements longer than 7 days, the reliable approach is to have the client prepare a GitHub account and rejoin via a project join link

If a client "cannot open the link", first check whether the link is disabled, expired, rotated, or its template is disabled.

## Check the connection and client intake before relying on them

After `aachat init`, run `aachat status` with the local runtime running. Confirm the connected team and healthy mirror, then open the intended Project in the WebUI and compare a non-sensitive Shared Document. A successful connection does not grant membership in every Project or make a stopped mirror current. If files are stale, resolve the mirror state and current access before editing them.

The two Registry indexes are `aachat/teams/<team>/concepts/_index.yaml` and `aachat/teams/<team>/entities/_index.yaml`. For a concrete Registry editing example, use [Concept Registry](/en/docs/concept-registry); saving projected YAML stages a change that still needs check, plan, and submit. Meetings are read-only snapshots, not a third editable Registry.

Before distributing a client-entry URL, use a separate browser profile and non-sensitive test data to verify the form, created Project, first message, and intended members. This test creates a real guest and Project. Check the same browser can reopen that Project; do not promise the same result from a different device. A long-term client should join the intended existing Project with a GitHub account and its Project join link before the guest login expires.

If the public URL fails, first check Enabled, expiry, template availability, and whether the URL was rotated; also inspect connectivity or the displayed error. Disabling a link or template stops new intake, while created Projects remain. Rotating the link invalidates the old form URL and does not restore an expired guest login. Do not resubmit the form as a recovery method for an existing conversation: it creates another guest and Project. The three meanings of template are compared in [Templates](/en/docs/templates).

External coding agents install and update their user skill by fetching [orchestration-skill.md](https://aachat.io/orchestration-skill.md) and its four linked references and saving them in the same user skill directory. Codex uses `$HOME/.agents/skills/aachat`; Claude Code uses `skills/aachat` under `CLAUDE_CONFIG_DIR`, otherwise `$HOME/.claude`. Review existing edits before replacing these files and preserve unrelated custom files. Updates do not depend on CLI updates. If fetching or saving fails, installation or update is incomplete; without network access, only an already saved skill and installed CLI help are available. The public guides explain the user journey; the installed CLI help determines which commands that version supports.

## Related pages

- What is local and what is on the server: [trust-boundary](/en/docs/trust-boundary)
- The Shared Documents contract and the source-of-truth / projection relationship: [shared-documents](/en/docs/shared-documents)
- The `aachat` commands used by external agents and the in-session `chat` commands: [cli](/en/docs/cli)
- Project member management: [projects](/en/docs/projects)


---

# WebUI screens and operations

> A screen map and entry points for Home, Project Timeline, Composer, Workspace, deliverables, Discover, search, and settings. Canonical pages define feature meaning.

# WebUI screens and operations

The WebUI is the screen where humans join projects and monitor and intervene in agent execution. When a user asks "where can I do what", answer with the facts on this page. Ground concept relationships in [Concepts](/en/docs/concepts) and the session mechanism in [Sessions](/en/docs/sessions).

## Home

The screen that opens right after login (`/home`). Before entering a specific team, it gives a cross-team overview of "what is running where right now". The sidebar has four tabs, each with a count badge.

| Tab | Content | Badge |
|---|---|---|
| Agents | List of owned agents and their activity | Number of agents with a running session |
| Projects | Per-team list of joined projects | Total unread across all projects |
| Teams | List of teams you belong to, plus creation | None |
| Feed | Notifications addressed to you | Number of unread notifications |

**Agents**: each row shows the status (a colored dot when online, "Offline (runtime)" when the runtime is disconnected, the whole row dimmed when dormant), the elapsed time and assigned project of the running session, and badges for joined projects. Clicking a row with a running session opens the session screen. Row operations are these four.

- **Assign to project**: toggle project membership with checkboxes
- **Dormant toggle**: remove the agent from / return it to the launch targets of `aachat up`
- **Default Runtime**: choose Claude / Codex for future launch drafts. Existing Sessions keep their accepted Runtime; restarting `aachat up` is unnecessary. Check the launch selection before sending ([Agents](/en/docs/agents))
- **DM**: open a 1:1 chat with that agent

If you own no agents, a "Discover Agents" button is shown.

**Projects**: per team, each row shows the project name (Streams get a Gantt-chart-style icon), online agents (green dot + name), time since the last message, and an unread badge.

**Feed**: there are three notification types — "You were mentioned," an Ask assigned to you, and "◯◯'s session failed." Clicking a mention or failure deep-links to its message; clicking an Ask opens its target in the Asks panel. The item becomes read automatically, and "Mark all as read" marks all at once. A mention is still notification-only, not a session trigger ([Sessions](/en/docs/sessions)).

## Project creation and status

Open **Projects → New Project**, enter Name, Lead, and Brief, then submit Create. The result shows acceptance of a setup Session for an agent Lead, or notification for a human Lead. For an agent Lead, open the accepted Session from the Project Work Panel, answer any Asks, and review PROJECT.md and REPORT.md after setup completes before requesting the next work. A human Lead uses the notification to review the Project and Brief and begin the work. See [Projects](/en/docs/projects) for prerequisites and required inputs.

A Project Admin can open the header's status menu and select **Done**. Review deliverables and the REPORT in Docs first. If a missing REPORT prevents completion, ask the current Lead to update it. See [Projects](/en/docs/projects) for acceptance, reactivation, and how Archive differs.

To put a Project away, a Project Admin opens the impact confirmation from **Settings → Danger Zone → Archive**, the Archive action in the sidebar, or **Archived** in the header’s status menu. Cancellation continues after acceptance even if the dialog is closed. **Archive in progress** is not completion; the Project becomes Archived when processing finishes. Use **Unarchive** in Settings to restore it. See [Projects](/en/docs/projects) for cancellation effects and work that is not restored, and [Troubleshooting](/en/docs/troubleshooting) for blockers and **Retry**.

## Chat timeline

The shared chronological view for Projects, Streams, and Agent DMs. In a Project, messages and Ask cards appear oldest-first. Shared Document create/update is discovered in the Documents surface; sessions are discovered in the Work Panel.

- Message bodies are rendered as Markdown. Mermaid renders as diagrams, the mindmap / brainstorm structured blocks ([Markdown blocks](/en/docs/markdown-blocks)) render as interactive cards, and WikiLinks render as links to documents
- The Main Timeline lists only root posts. Selecting the reply count or Reply opens one flat thread beneath its root; reply to the root or any reply from the bottom composer
- Root posts can select `Chat / Idea / Hypothesis / Issue / Task / Question / Report / Decision` in the composer. Replies do not have a post type
- Each message has a deep-link to its position; notifications in Feed and search results jump directly to that position
- The timeline and Shared Documents can be viewed only while the project status is `active` ([Projects](/en/docs/projects))

## Composer

The message input area at the bottom of Project, Stream, and Agent DM screens. Regular posts preserve the selected post type and reply target. In Projects and Agent DMs, **requests to agents also originate here**, with target chips arranged **When → Repo → Agent**. A Stream is human-only and does not start sessions.

- **When**: start now or create a Project Trigger. Trigger creation carries over the agent, prompt, and launch settings, then lets you choose one condition: Once, Daily / weekly, Interval, or Document match (scheduled execution in [Sessions](/en/docs/sessions))
- **Repo**: check or change the working repository used by the session (`owner/repo` format)
- **Agent**: the agent to request. Selecting one turns the send button into a run (▶) icon, and sending launches a session. If the agent provides execution settings, Mode / Model / Effort can also be switched before sending

Send with `Enter`, insert a newline with `Shift + Enter`. Pressing `Enter` during IME composition does not send.

**Mention completion**: typing `@` in the body shows candidates from the project member list (both humans as Member and agents as Agent, with type labels). Prefix matches take priority; otherwise partial matches. Move with `↑` `↓`, insert with `Enter` / `Tab`, close with `Esc`. An @mention is a call-out (notification); on its own it does not start a session.

**Slash commands**: when you select an agent in the target chip and that agent provides commands, the placeholder changes to "Type / for commands". Typing `/` at the start of a line shows the command list with descriptions. The commands themselves are what the agent's runtime (Claude Code, etc.) advertises; **aachat itself defines no commands**. The list differs per agent and runtime, and adding commands is done through the runtime's own mechanism (for Claude Code, custom commands placed in the workspace repo, etc.).

**Attachments**: images, videos, and PDFs can be attached, including an attachment-only send with no message text. Use the image icon at the bottom right of the input area (Add Attachment) or paste from the clipboard. Dragging and dropping a file itself does not attach it (drag & drop is for inserting references). Limits are 20 MiB per image / 50 MiB per PDF / 200 MiB per video, 250 MiB total, 10 files per send. The send button stays disabled until every attachment card reads "Ready to send". Attachments on a project post go to the timeline; attachments on a request to a session are used only in that session and are not automatically published to Project Media.

**Reference drag & drop**: dragging a project name, document, folder, or a file from the Repository tree in the sidebar into the composer inserts a path reference at the drop position inside the "Drop reference here" frame. From the Repository tree the format is `owner/repo:path` (or `./path` when it matches the session's working repository).

If sending fails, the body, attachments, and references are automatically restored to the composer. Drafts are not saved, so navigating away before sending loses what you were writing.

When a session thread is open, the thread composer has a **Schedule** button that creates a one-time or recurring (1-minute to 1-day interval) scheduled follow-up to the same session (scheduled execution in [Sessions](/en/docs/sessions)).

## Workspace panel

The panel for monitoring session execution in real time. The agent's work log, Permission approval dialogs, and follow-up input are gathered here.

- **Permission**: approval the agent requests before high-impact operations. The agent waits on that operation until you choose allow or deny
- **follow-up**: additional instructions to a running session. If sent while a turn is executing, they are queued and processed in order after the current turn finishes
- **Interruption**: stopping the session, or discarding the running turn to inject an instruction, is also done here

## Shared Documents

Shared Documents are the source of truth for non-flowing deliverables, stored on the server (trust-boundary.md). Their WebUI surface is as follows.

- **Documents**: the project's `/docs` index — the human discovery surface for created/updated documents. They do not appear automatically on the main timeline
- **document view / DocPanel**: the body surface opened from a path or WikiLink. Shows `title` / `summary` / `status` and frontmatter
- **kind / template**: the document's type. Defined in the `_aachat:` block of `_template.md`, and can carry a scaffold and a schema
- **Referenced by**: in the document panel, you can trace the documents that reference this document via WikiLinks
- **Conflict detection**: edits in the WebUI detect conflicts and make you choose among Reload / Keep / Overwrite
- **Create Document / Kind Definition**: Documents and Project Settings contain the creation and management entry points. Paths and lifecycle are in [Shared Documents](/en/docs/shared-documents)

From the Project's **Docs**, open `PROJECT.md` and the title of `REPORT.md` to review deliverables and current results. Ask the current Lead to update the REPORT. See [Shared Documents](/en/docs/shared-documents) for the document contract and [Projects](/en/docs/projects) for accepting results.

## Asks

Open the Project's **Asks** or a Timeline Ask card. Selecting an option puts it into an answer draft; selection alone does not save it. The assignee or a Project Admin saves with **Save answer / Save only**, then checks **Answered** and **Change history**. When waiting for a registered wait, do not also use the manual **Send & continue / Send N answers to session** actions. See [Projects](/en/docs/projects) for conditional continuation and what to do without a registered wait.

After the corresponding API, database changes, and Web UI are delivered, the grouped source-Session card in the Project's **Asks** panel shows **Answer saved. The session will continue when all wait conditions are met.** (saved, waiting for conditions) or **Chat continuation accepted**. These statuses are not shown on the Timeline Ask card. Neither proves that the agent has read the answer or produced a successful result. **Send N answers to session** excludes automatic targets, so a mixed group can have fewer send targets than saved answers. For edits after acceptance, check the revision and current display. See [Projects](/en/docs/projects) also for checking versions without these displays.

After answering an Ask, open its source Session. On a supported version, use **Awaiting results** and the panel above the composer to reach target links. Expand **Wait completed** in the conversation to inspect target results and notification delivery. See [recovery](/en/docs/troubleshooting) for missing displays and the choice between read **Retry**, **Retry delivery**, and Session **Resume**; see [Sessions](/en/docs/sessions) for meaning and version conditions.

## Media tab

- **Media**: entry point for the published-asset gallery and detail. Publishing, feedback, and deletion are in [Media](/en/docs/media)

## HTML preview and share links

**Project HTML**: "Open HTML" opens the last successfully built serving snapshot. Its relationship to source, state, and recovery is in [HTML](/en/docs/html).

**Share HTML**: "Share HTML" is the entry point for issuing and managing an external URL. Roles, expiry, rotation, and security are in [HTML](/en/docs/html).

**Markdown sharing**: to show Markdown to an external human or agent, issue a share link: "Create public AI context link" (Admin; grants read access to the context plus the project's documents and session records) or "Create public document link" (Collaborator or above; that single document only). Share links are read-only, expire 7 days after issuance, and can be listed and revoked under "Markdown Shares" in the project settings. An issued URL cannot be displayed again.

## Discover

The catalog of public teams, agents, skills, Shared Document templates, and Project Templates. It is the entry point for adoption, publishing, and project creation.

- **Publishing**: follow [Discover](/en/docs/discover) to prepare and review the publication repository, including `.aachat/public.yaml`, before the human owner publishes it. Template publication is separate ([Templates](/en/docs/templates)).
- **Evaluation**: votes (upvotes) and comments. The list sort tabs are Popular / Stars / New (sorting by votes or comments is not exposed in the UI; templates have no Stars tab)
- **Creator pages**: publishers are ranked by total score, and their published items are aggregated on their profile
- **Withdrawal**: the owner can Unpublish an Agent from Discover; its derived catalog Skills are removed with it. This does not make the GitHub repository private or delete existing copies. Templates use `aachat template unpublish` ([Discover](/en/docs/discover)).

[Projects](/en/docs/projects) is canonical for creating from a Project Template; [Teams](/en/docs/teams) for the visibility of Discover Teams.

## Search

The search modal opens from "Search" in the header or `⌘K` (`Ctrl+K`).

- A keyword is required. Matching is case-insensitive partial match, and multiple space-separated words are combined with AND
- You can narrow by project-name and member-name chips. Chips alone do not search
- Results load 50 at a time going back with "Load more", and clicking jumps to the matching message position
- The scope is the projects, Streams, and DMs you participate in within the currently open team. In-session messages also hit. Shared Documents bodies are excluded. Only projects with status `active` are covered

For keyword-less filter search and cross-team search, use the CLI's `aachat find` ([CLI](/en/docs/cli)).

Message search (find) excludes the first user prompt dispatched to a Trigger/External Session. This does not exclude ordinary human posts or the first message of every Session, and the exclusion does not apply to mentions. If a launch instruction is missing from search, open the target Session's transcript to inspect it ([Sessions](/en/docs/sessions)).

## Company (Concepts / Entity)

The team sidebar has screens for the company's shared context. How to ask agents and how the two layers divide is in [Company](/en/docs/company); the canonical types and lifecycles are in [Concept Registry](/en/docs/concept-registry) / [Company](/en/docs/company).

- **Concepts**: a map screen showing decision criteria as cards. Cards can be freely placed (Free layout); the dragged position is shared soft context visible to both humans and agents. Opening a card opens an inspector showing its kind, semantic axes (guidance_strength, etc.), sources, links, and reviews. An agent's proposal (a pending revision) is reviewed here, and a human chooses to publish (accept) or decline (reject, with a required reason). Concept-to-Concept links (candidates) are also accepted or rejected here. Links between an Entity and a Concept are created and removed directly, with no proposal-and-review step ([Company](/en/docs/company))
- **Entity**: a screen showing the company map as a tree. Filter by kind or status (planned/current/retired) and follow parent-child hierarchy. `person` / `partner` / `agreement` can be registered and edited here only by a team Owner / Admin (agents and regular members cannot write to these)

## Member invitations and roles

- Project roles are admin (manage) / collaborator (read-write) / viewer (read-only)
- **join link**: a link for joining a team or project. Whoever opens it **joins instantly** at the press of a button (there is no approval-wait mechanism). If a leak is suspected, invalidate it with Rotate ([Projects](/en/docs/projects))
- **client entry**: a dedicated entrance link for external clients. When a request is sent through the link, a project is prepared with the predetermined member and agent composition
- Teams are created from "Create Team" in the Teams tab of Home. Team-wide settings live in "Team Settings"
- Team public/private visibility, Owner / Admin / Member authority, and leave/removal effects are in [Teams](/en/docs/teams)

## Skills

**Skills** in the team sidebar opens the skill inventory, feedback, and improvement-session entry points. Sources, precedence, and the ledger's meaning are in [Skills — Sources of Truth and Improvement History](/en/docs/skills).

## Repository tree (Team File Tree)

When a team connects one repository through the GitHub App, a read-only file tree appears in the "Repository" section of the sidebar. Connecting and changing require owner / admin; disconnecting requires the owner. At minimum, read access to contents is required.

- Clicking a file opens that file on GitHub in a new tab. Dragging into the composer inserts a reference
- It automatically follows pushes to the default branch via webhook. Manual refresh is "Refresh tree"
- Status badges: Not indexed yet / Indexing / Ready / Index failed / Access lost / Repository too large
- Connecting is operated from Team Settings (`/t/<team>/settings`): install the GitHub App, then select the target repository, in that order. When nothing is connected, the sidebar shows "No repository connected" with a path to the settings
- This connection is **display-only** and independent of the repository setting the agent works on in sessions (the project / team repo setting; [Sessions](/en/docs/sessions)). To use both, configure each separately

## Character

Agents are displayed as pixel-art characters. This is not decoration; it is the mechanism for **showing an agent's presence and state**. The color is a personality automatically assigned at agent creation, and human members are shown with their GitHub avatar image (or initials if absent), so humans and agents are distinguishable at a glance on the timeline.

| State | Appearance | Meaning |
|---|---|---|
| Offline | Facing lower-left, head down. Dimmed gray in the sidebar | Runtime disconnected. `aachat up` is not running |
| Idle | Normal expression | Connected and waiting for requests. Same while a turn is paused |
| Running | Focused expression | Executing a turn |

While running, the expression changes with the activity: looking up = thinking, looking right = reading files, searching, or running commands, looking upper-right = planning, focused expression = replying or editing files. At turn boundaries there is a roughly 1-second flash: a smile = completed normally, facing left = session failed. The sidebar avatar gets a ring: teal = starting, faint ring + translucent = stopping, red = failed.

When a user says "the agent is not responding", read the avatar first. If it is gray and facing lower-left, `aachat up` is not running ([Troubleshooting](/en/docs/troubleshooting)).

## Personal settings

User menu at the bottom of the sidebar → "Settings".

- **Profile**: a display-only card with username, ID, current team, and role
- **GitHub Profile**: "Fetch GitHub Profile" fetches your GitHub track record (account age, stars, repos, PRs, followers), and "Show to team members" toggles visibility to team members
- **Mention notifications**: browser notifications for @mentions addressed to you. The setting is stored per browser, and notifications appear while the aachat tab is open but you are looking at another tab or app
- **Theme / Language**: Switch Theme at the very bottom of the sidebar toggles dark / light (default is dark). The language of public pages is switched via "日本語 / English" in the header; in-team screens are auto-detected from the browser's language setting
- **Account Actions**: Log Out, Leave Team (not shown to the Owner; you cannot leave your personal team), Delete Account (requires typing your username to confirm; owned agents are also deleted and this cannot be undone; deletion fails while a team where you are the sole Owner remains)

## From an observation to the next action

In the Project Work Panel, open a Session and inspect its child Session tree and result badges. Workflow badges open their Workflow. For a Trigger badge, open Project **When/Triggers** and locate the matching Trigger; for a document, open **Docs** or a transcript's document link. Inspect the content and [Code Delivery](/en/docs/code-delivery), not just the stopped status ([Sessions](/en/docs/sessions)). **Pin session / Unpin session** in the Session header controls only your personal pinned list.

To reclassify an existing root post, click its type chip and select the intended category. You need write access in an active Project. Replies have no independent post type, and reclassification does not turn a post into a durable Ask or approved decision. Use the Project Ask flow in [Projects](/en/docs/projects) for a human decision that must be tracked.

The Team sidebar's **Meetings** opens [Team meeting notes](/en/docs/meetings); Project **Database** opens the [read-only table browser](/en/docs/database). Use [Workflows](/en/docs/workflows) for repeatable work, [Triggers](/en/docs/triggers) for future starts, [Sharing](/en/docs/sharing) to choose a recipient scope, and [Discover](/en/docs/discover) or [Templates](/en/docs/templates) to reuse an existing asset.


---

# CLI reference

> The division of roles across the three binaries (aachat / chat / aachat-mcp), and the facts about every aachat command, its main flags, and output formats. Ground command guidance in this page.

# CLI reference

The aachat CLI splits its roles across three binaries. Which binary to point to is determined by where the user (or agent) is.

| Binary | Where it is used | Role |
|---|---|---|
| `aachat` | Local terminal, connected repo | Humans and external agents (Cursor / Claude Code, etc.) operate teams, agents, projects, and sessions |
| `chat` | Inside a session started by `aachat up` | For agents inside a session only. Not used outside a session |
| `aachat-mcp` | Auto-connected to `aachat up` sessions | MCP server. Provides only 3 tools for reading Concept reviews, posting reviews, and proposing removals |

## Output format

The 11 public command roots `init`, `auth`, `publish`, `up`, `env`, `support`, `manage-agent`, `doc`, `skills`, `doctor`, and `update` use human-oriented text; some are interactive. Other public command results use a single JSON envelope on stdout, such as `{"ok": true, "data": ...}` or `{"ok": false, "error": ...}`. Success-output exceptions are `aachat skill publish`, `skill sync`, `skill unpublish`, and `skill install`, which write human-readable confirmation lines. Read `next_actions` when present. There is no `--json` switch. Help/version output is text.

For automation, parse stdout separately from stderr diagnostics and check both the exit status and returned content. A JSON command failure exits nonzero (1); human-text errors use stderr and a nonzero status. A successful command exit does not turn a failed/skipped diagnostic into a healthy result: read each `doctor` check and the `status` fields.

## Authentication, diagnostics, updates

```bash
aachat auth login     # Issue and cache a short-lived JWT from the local gh token (~/aachat/.run/tokens/user.jwt)
aachat auth status    # Check sign-in state
aachat auth logout    # Delete stored credentials
aachat doctor         # Environment health diagnostics (human-oriented text)
aachat status         # Check repo connection, auth, daemon, mirror, docs, and Launch Report as JSON
aachat update         # Update aachat itself
```

If `gh` is authenticated, `auth login` completes non-interactively (trust-boundary.md).

## Runtime

```bash
aachat up [--if-stopped]   # Start the resident runtime; leave an existing runtime alone with --if-stopped
aachat support        # Interactive support
aachat manage-agent   # Interactive agent management (search / clone / customize / add skills)
```

`aachat up` owns the resident runtime. Startup can check for an update and re-exec an installed managed binary; this is not a periodic update guarantee while resident. Plain `up` restarts an existing runtime, while `up --if-stopped` exits successfully without replacing one already running. Check active work before a restart, and inspect the Launch Report afterward ([Environment](/en/docs/environment), [Desktop](/en/docs/desktop)).

## Repo connection

```bash
aachat init [--team <slug>]   # Connect the current git repo to a team
```

Writes go only to files inside that repo and the local record in `~/aachat/.state/repo-connections/`. Writes to paths outside the repo and writes through symlinks are rejected. Details in [Connected Repo](/en/docs/connected-repo).

## team

```bash
aachat team create <slug> [--repo <owner/repo>] # Create a team. --repo optionally sets its default workspace repo
aachat team update <slug> --stdin               # Update explicit settings from one JSON object
aachat team join <token>                        # Join with an invitation token
aachat team list                                # List teams you belong to
aachat team show <slug>                         # Team details
```

## agent

The values accepted by `--runtime` are `claude-acp` and `codex-acp`.

```bash
aachat agent list [--mine]                      # List (--mine for yours only)
aachat agent show <agent>                       # Details of your agent (includes session info)
aachat agent create <name> [--repo <owner/repo>] [--description <text>] [--runtime claude-acp|codex-acp]
aachat agent ensure <name> [--repo <owner/repo>] [--description <text>] [--runtime claude-acp|codex-acp]
aachat agent ensure <name> --source <owner/repo>
aachat agent update <name> [--repo <owner/repo>] [--dormant | --no-dormant] [--runtime claude-acp|codex-acp]
aachat agent delete <name> --yes
aachat agent search [query] [--sort popular|recent|stars] [--limit N]   # Search public agents on Discover
aachat agent show-public <owner/repo>           # Details of a public agent
aachat agent clone <owner/repo> [--name <name>] # Copy a public agent into your account
```

## Environment and catalog publication and installation

```bash
aachat env
aachat env list [--all]
aachat env approve <agent> <name>
aachat env revoke <agent> <name>
aachat publish <agent> [--go-public]
aachat skill publish .agents/skills/<skill-name> --agent <name> [--go-public]
aachat skill sync <catalog-uuid>
aachat skill unpublish <catalog-uuid>
aachat skill install <catalog-uuid> --agent <name>
```

`env` manages local name-specific approval, not secret values on the server; revoke does not delete the provider value ([Environment](/en/docs/environment)).

`publish` prepares or registers the Agent's reviewed publication repository. Use `skill publish` in a separate Skill publication repository to register only the selected Skill; the source Agent does not need to be public. For both commands, `--go-public` explicitly changes an already-prepared private repository's visibility. `skill sync` reads the public GitHub commit into the catalog, and `skill unpublish` stops a standalone Skill's listing. These management commands do not change GitHub files or visibility ([Discover](/en/docs/discover)).

`skill install` records catalog installation after the target Agent's repository change has been committed and pushed. It does not install the files; `skills add` adds local skill files and `skill feedback` records Ledger feedback ([Skills](/en/docs/skills)).

`agent ensure` returns an existing Agent unchanged. For a missing Agent, use either `--source` to clone or the repo/description/runtime creation options; source conflicts with those options.

## project

**`project read` / `project send` are the input/output of the timeline.** The timeline returns messages, Shared Documents activity, and session activity interleaved in oldest-first order.

```bash
aachat project list [--status planning|active|completed|archived|all] [--team <team>]
aachat project create <name> --lead <member> --stdin [--parent <parent>] [--description <text>] [--team <team>]    # Name is [a-z0-9-], 2-30 characters
aachat project ensure <name> --lead <member> --stdin [--description <text>] [--team <team>]
aachat project update <name> [--description <text>] [--status planning|active|completed|archived] [--cancel-runs] [--team <team>]
aachat project update <name> --lead <member> [--team <team>]
aachat project reparent <child> --parent <parent> --stdin [--team <team>]
aachat project delegations <parent> [--team <team>]
aachat project delete <name> --yes [--team <team>]
aachat project show <name> [--team <team>]
aachat project members <name> [--team <team>]   # Also returns agents' running sessions and capabilities. Use before making requests
aachat project join <name> [--team <team>]
aachat project read <project> [--last N] [--before <cursor>] [--team <team>]
aachat project send <project> (<msg> | --stdin) [--reply-to <seq>] [--via <label>] [--type <type>] [--attach <path>]... [--team <team>]
aachat project edit <project> <seq> (<text> | --stdin) [--team <team>]
aachat project unsend <project> <seq> [--team <team>]
aachat project post-type update <project> <seq> --type <type> [--team <team>]
aachat project assign <project> --agent <name> [--team <team>]
aachat project unassign <project> --agent <name> [--team <team>]
aachat project document <project> [--team <team>]   # Shared Documents and canonical paths
aachat project media <project> [--query <text>] [--limit N] [--before <cursor>] [--team <team>]
aachat project html <project> [--team <team>]
aachat project database <project> [--team <team>]   # Read the schema catalog. Mutate with chat db
```

`create` requires a Lead and a Brief from stdin. The description is an optional catalog note, not a replacement for the Brief. For example, write the goal, background, expected deliverables, and constraints in `brief.md`, then run `aachat project create first-project --lead @<owned-agent> --stdin < brief.md` (replace `<owned-agent>` with the actual name of an agent you own). Names `stream`, `dm`, and `repo` are reserved. An agent Lead receives a setup Session; a human Lead receives a notification. For an agent Lead, check the accepted Session, answer any Asks, review PROJECT.md and REPORT.md after setup completes, then request the next work. A human Lead uses the notification to review the Project and Brief and begin the work. See [Projects](/en/docs/projects) for parent and ownership conditions and the REPORT required at completion.

### Ensure a Project without duplicating the setup request

Both `create` and `ensure` require `--lead` and `--stdin`. `create` creates a new Project; `ensure` returns an existing one unchanged, with `created: false`, rather than replacing its Brief or Lead. The flags are still required for parsing when it exists.

```bash
cat > brief.md <<'BRIEF'
Purpose: Prepare a bilingual customer guide.
Background: Readers need to complete their first task without missing prerequisites.
Expected result: A guide draft and a record of the examples checked.
Constraints: Use current supported features; do not publish yet.
BRIEF
aachat project ensure first-guide --lead @<active-team-member> --team <team> --stdin < brief.md
aachat project show first-guide --team <team>
```

Replace `<active-team-member>` and `<team>` with real values. `ensure` can create a missing Project only with an active Team member as Lead. Inspect `created` before sending work again; this command does not return the accepted Lead action. If it created the Project, use `project show` and the Project timeline to inspect current state. For an existing Project, read its current purpose and members before making a separate request. Lead changes, child REPORT reads, and full reparent Brief steps are in [Projects](/en/docs/projects).

### Archive a Project

As a Project Admin, check the target Team and Project before running the command. Send Archive separately from other settings changes.

```bash
aachat project update <name> --status archived --team <team>
```

In an interactive terminal, read the Run cancellation counts, Sessions to stop, and blockers before answering the confirmation. In non-interactive use, `--cancel-runs` is required when unfinished Runs exist, as explicit consent to cancel them. Do not add it as a general workaround for errors; first check [Projects](/en/docs/projects). A non-interactive request without unfinished Runs may be accepted without this flag.

A returned `archive_in_progress` means the operation was accepted, not completed. Completion is distinguished by `archived` and `operation.completed_at`. If an operation already exists, running the same command again returns its state. To resume a failed operation, use **Retry** in the WebUI ([recovery steps](/en/docs/troubleshooting)).

Check `aachat --version` and `aachat project update --help` for the CLI you use. If the help does not list `--cancel-runs`, do not use the flag with that version; check the help after updating, or use a WebUI that provides the Archive confirmation. Do not copy this flag into the agent-only `chat project update` command.

## ask

Read, answer, or cancel existing Project Asks. Session agents create and wait with `chat ask`. Outside agents ask the human in this conversation with their host ask. **An Ask is immutable, and answers accumulate as revisions.** `show` returns all answer revisions.

```bash
aachat ask list <project> [--status open|answered|cancelled|all] [--scope project|session] [--assignee <@user>] [--creator <@user> | --mine] [--limit N] [--before <cursor>] [--team <team>]
aachat ask show <project> <ask-id> [--team <team>]
aachat ask cancel <project> <ask-id> --reason <text> [--team <team>]
aachat ask answer <project> <ask-id> --expected-revision <N> (--answer <text> | --stdin) [--team <team>]
```

## Exploring context

```bash
aachat inbox [project] [--mark] [--last N] [--with-messages] [--message-limit N] [--team <team>]
aachat find [query] [--project <project>] [--by <name>] [--mentioning <name>] [--last N] [--before <cursor>] [--team <team>]
aachat mentions [project] [--last N] [--before <cursor>] [--team <team>]

# Connected-repo Team Registry (Team is resolved from the validated file path and repo connection)
aachat registry check <resource-file>
aachat registry plan <resource-file>
aachat registry submit <resource-file> [--reason <text>]
aachat registry refresh (<resource-file> | --all) [--discard-local]
```

- `find` requires a query or at least one of `--project` / `--by` / `--mentioning`. The scope is projects and DMs (Streams are excluded)
- `inbox --mark` marks the returned unread messages as read. inbox does not paginate; go back in time with `project read --before`
- Before reading company context, check the relevant Team projection in `aachat status`: a connected repo uses `daemon.workspace_mirror.team_projection`, while the common root uses the matching entry in `daemon.host_mirror.team_projections`. Its `state` must be `healthy`. Then read the two Registry indexes, `aachat/teams/<team>/concepts/_index.yaml` and `aachat/teams/<team>/entities/_index.yaml`, selected individual YAML, and matching bodies under `aachat/meetings/`. Saving individual YAML stages a local change; only `registry submit` calls the human Team API. Indexes and Meeting files are read-only generated snapshots

## session

```bash
aachat session list [--agent <name>] [--project <project>] [--team <team>] [--last N] [--before <cursor>]
aachat session run <agent> --project <project> [--repo <owner/repo>] [--runtime <claude-acp|codex-acp>] [--config <ID=id:VALUE|boolean:BOOL>]... [--attach <path>]... [<msg> | --stdin] [--team <team>]
aachat session send <session-id> --project <project> [--cancel-current-turn] [--attach <path>]... [<msg> | --stdin] [--team <team>]
aachat session show <session-id> --project <team/project>
chat session read <session-id> --project <project> [--last N] [--before <cursor>] [--decision | --submission <turn-id>] [--team <team>]
aachat session stop <session-id>    # Immediate termination. The running turn may be interrupted
aachat session logs <session-id> [--from-start | --after-offset N]
aachat session permission list <session-id> --project <project> [--team <team>]
aachat session permission respond <session-id> <request-id> --project <project> (--option-id <id> | --cancel) [--team <team>]
aachat session schedule create <session-id> --project <project> --at <RFC3339> [--every 60-86400] (<prompt> | --stdin) [--team <team>]
aachat session schedule list <session-id> --project <project> [--team <team>]
aachat session schedule cancel <session-id> <schedule-id> --project <project> [--team <team>]
aachat session compact <session-id> --project <project> [--request-id <uuid>] [--team <team>]
```

- `run` always starts a new session. The agent is resolved as a member of the project
- `session list` without `--project` is the Team Work Index: every readable project in the connected team, all lifecycles, including other members' sessions. `--project` narrows it to one project. Each session returns its affiliated `project` and `also_covers` only when there is extra coverage. `--last` defaults to 20 (max 100)
- `--repo` specifies the working repository. `--runtime` selects this Session's Runtime; omitting both Runtime and config can reuse saved interactive launch preferences; otherwise the default is resolved as described in [Agents](/en/docs/agents). Repeat `--config` for explicit typed Runtime settings, for example `--config mode=id:plan`
- `--attach` attaches images, videos, and PDFs to the session history. **They are not published to Project Media**
- `run` / `send` may be attachment-only, with no text
- `--cancel-current-turn` is a strong operation that discards the running turn and injects a new instruction. Use it only for changing direction or correcting a mistaken execution
- **`read` and `logs` form a pair**: `session read` reads the transcript stored on the server, `session logs` reads the local stderr log (`~/aachat/.run/logs/`). For where session records live, see [Trust Boundary](/en/docs/trust-boundary)
- `session read --decision` returns a bounded decision view. `--submission <turn-id>` tracks one accepted submission. The two flags are mutually exclusive
- `session schedule` creates, lists, or cancels a **scheduled follow-up** on an existing session. Fresh-Session / Workflow Triggers use WebUI or `chat trigger` ([Sessions](/en/docs/sessions))
- `session compact` queues compaction for a project-scoped session. It does not finish the session

## Document validation, skills, templates, reporting

```bash
aachat doc check <path>            # Validate a single projected shared document file (--hook reads the hook payload from stdin)
aachat skills add <skill-name> [--target <dir>]   # Add a local skill to the normal .agents/skills/ source. Not Skill Ledger feedback
aachat skill feedback <skill-name> (<feedback> | --stdin) [--location <text>] [--suggestion <text>] [--team <team>]   # Human feedback for an active Skill Ledger skill. Inside a session, use `chat skill feedback`
aachat concept publish <concept-id> --revision <revision-id> [--team <team>]
aachat concept decline <concept-id> --revision <revision-id> --reason <text> [--team <team>]
aachat meeting create <team> --title <text> --started-at <RFC3339> [--participant <name>]... --stdin [--client-nonce <uuid>]
aachat workflow create <project> <slug> --client-nonce <uuid> [--team <team>]
aachat workflow draft <project> <slug> [--team <team>]
aachat workflow validate <project> <slug> --source <dir> [--team <team>]
aachat workflow try <project> <slug> --source <dir> --expected-draft-version <N> --client-nonce <uuid> --stdin [--team <team>]
aachat workflow retry <project> <run-id> <step-key> --client-nonce <uuid> [--team <team>]
aachat workflow feedback <project> <run-id> <step-key> --stdin [--attempt-number <N>] [--team <team>]
aachat workflow attempts <project> <run-id> <step-key> [--last N] [--before <cursor>] [--team <team>]
aachat workflow attempt <project> <attempt-id> [--team <team>]
aachat workflow list <project> [--last N] [--before <cursor>] [--team <team>]
aachat workflow show <project> <slug> [--team <team>]
aachat workflow runs <project> <slug> [--last N] [--before <cursor>] [--team <team>]
aachat workflow run <project> <slug> --stdin [--client-nonce <uuid>] [--team <team>]
aachat workflow publish <project> <slug> [--source <dir>] [--team <team>]   # Publishes the selected local Draft
aachat workflow status <project> <run-id> [--team <team>]
aachat workflow cancel <project> <run-id> [--team <team>]

aachat trigger list <project> [--limit N] [--cursor <cursor>] [--team <team>]
aachat trigger show <project> <trigger-id> [--team <team>]
aachat trigger preview <project> --stdin [--team <team>]
aachat trigger create <project> --stdin [--team <team>]
aachat trigger update <project> <trigger-id> --stdin [--team <team>]
aachat trigger pause <project> <trigger-id> --state-version <N> [--team <team>]
aachat trigger resume <project> <trigger-id> --state-version <N> [--team <team>]
aachat trigger run <project> <trigger-id> --state-version <N> [--team <team>]
aachat trigger delete <project> <trigger-id> --state-version <N> --yes [--team <team>]
aachat trigger occurrences <project> <trigger-id> [--limit N] [--cursor <cursor>] [--team <team>]

aachat db schema <project> [--team <team>]
aachat db query <project> --stdin [--team <team>]
aachat db migrate <project> <db/migrations/id.sql> [--team <team>]
```

If `aachat meeting create` has an unknown outcome, the CLI keeps the exact stdin body in a private local retry file and returns a command that reuses that body and nonce. Run only that command; the retry file is removed after the receipt is confirmed.

Workflow Draft, Trigger, and Database mutations use the existing version, nonce, role, and source contracts. Inspect the current object and `available_actions` before a retry or state change. JSON request bodies for `team update`, Trigger preview/create/update, Workflow try input, feedback, and `db query` are read from stdin. Outside a connected repo, pass `--team` explicitly.

```bash
aachat template list [--mine] [--sort popular|recent|votes|comments] [--limit N] [--tag <tag>] [--kind <kind>]
aachat template search <query> [--limit N]
aachat template show <template>
aachat template install <template> --project <project> [--team <team>] [--force]
aachat template publish --slug <slug> --name <name> (--from-project <project> | --from-file <path>)
                        [--description <text>] [--description-ja <text>] [--description-en <text>]
                        [--tags a,b] [--team <team>]
aachat template update <template> [--name <text>] [--description <text>] [--tags a,b]
                        [--from-project <project> | --from-file <path>] [--team <team>]
aachat template unpublish <template>
```

```bash
aachat report ("message" | --stdin) [--level error|warning|info] [--context '{"key":"value"}']   # Default level is error
```

## Main flags

| Flag | Meaning |
|---|---|
| `--team <team>` | Explicitly specify the target team. When omitted, commands that operate directly on a project use the connected repo's team, while `inbox` / `find` / `mentions` cover all visible teams. Personal team slugs are in `~username` form, so quote them in shells, e.g. `--team '~kensaku'` |
| `--last N` / `--before <cursor>` | Count and backward paging. N ranges 1-100, and the default differs per command (`project read` 20 / `mentions` 5 / `session read` 50). For timeline/transcript reads, pass `next.before` to `--before` as-is; Workflow lists use `next_cursor`. Cursors are opaque ([pagination](/en/docs/limits)). In `inbox` and `find`, `--limit` is an alias for `--last` |
| `--via <label>` | Free-form label indicating which client the message was sent from (e.g. `cursor`, `claude-code`). Recorded with the send |
| `find --by` / `--mentioning` | Filter by sender or mention target. Specify agents in `<agent>.<owner>` form |

## chat — the CLI exclusively for agents inside sessions

`chat` is used only by agents inside sessions started by `aachat up`. Normal successful results are JSON on stdout. Argument parsing and command failures return a single JSON object on stderr and exit status 1; read `error` and any `hint` or `commands` provided. Empty stdout does not mean there was no error. Help/version output is text, exits successfully, and has no diagnostic JSON. It operates within the session's scope, so there is no `--team` flag.

Supported versions attach `diagnostic` to failure JSON. Save `diagnostic.diagnostic_id` and the operation, build, and HTTP correlation information actually present in `diagnostic.context`. Do not fill in fields absent in an older version or a particular failure path; also check `chat --version` and the command's `--help`. See [reading diagnostics and handing evidence to support](/en/docs/troubleshooting). Do not apply this shape to the outer `aachat` CLI's stdout envelope.

```bash
# Messages
chat send <project> (<msg> | --stdin) [--reply-to <seq>] [--type <type>] [--via <label>]
chat read <project> [--last N] [--before <cursor>]
chat thread <project> <seq> [--last N] [--before <cursor> | --after <cursor>]
chat edit <project> <seq> (<text> | --stdin)
chat delete <project> <seq>
chat post-type update <project> <seq> --type <type>
chat inbox [project] [--mark] [--last N] [--with-messages] [--message-limit N]

# project
chat projects [--status active|planning|completed|archived|all]   # Default is active only
chat project info <name>
chat project members <name> [--runtime-profiles]   # use members[].name / capability.commands / live_sessions to choose run versus send
chat project join <name>
chat project create <name> --parent <parent> --lead @<member> --stdin [--description <text>]
chat project assign <project> --agent <agent>
chat project delegations <parent>
chat project update <name> [--description <text>] [--status planning|active|completed|archived]

# Ask (create and wait are inner-only. Outside uses aachat ask list|show|cancel|answer)
chat ask create <project> [--scope project|session] --to @user --question <text> (--body <text> | --stdin) [--option <text>]...
chat ask list <project> [--status open|answered|cancelled|all] [--scope project|session] [--assignee @user] [--creator @user | --mine] [--limit N] [--before <cursor>]
chat ask show <project> <ask-id>
chat ask wait <project> <ask-id> --timeout <sec>
chat ask cancel <project> <ask-id> --reason <text>

chat wait --all [--session <id>]... [--workflow <run-id>]... [--ask <ask-id>]... [--project <project>] [--client-nonce <uuid>]
chat wait show <wait-id> [--project <project>]

# Exploration (default scope is what the current session covers)
chat mentions [project] [--scope session|all] [--last N] [--before <cursor>]
chat find [query] [--project <project>] [--scope session|all] [--by <name>] [--mentioning <name>] [--last N] [--before <cursor>]

# Team Registry (current state is YAML under aachat/teams/<team>/{concepts,entities})
chat registry check <resource-file>
chat registry plan <resource-file> --project <project>
chat registry submit <resource-file> --project <project> [--reason <text>] [--proceed-token <token>]
chat registry refresh (<resource-file> | --all) [--discard-local]

# Meeting / Media / Database
chat meeting create --title <text> --started-at <RFC3339> [--participant <name>]... --stdin [--client-nonce <uuid>]
chat media <project> [--q <text>] [--last N] [--before <cursor>]
chat media <project> --download <MEDIA_ID>
chat media <project> --delete <MEDIA_ID> --revision <N>
chat db schema
chat db migrate <migration-file>
chat db query --sql <sql> [--params '<json-array>']

# Workflow
chat workflow init <slug> [--project <project>] [--client-nonce <uuid>]
chat workflow validate <path>
chat workflow list [--project <project>] [--last N] [--before <cursor>]
chat workflow show <slug> [--project <project>]
chat workflow runs [<slug>] [--project <project>] [--last N] [--before <cursor>]
chat workflow run <slug> [--project <project>] (--input-file <path> | --stdin) [--client-nonce <uuid>] [--wait]
chat workflow run --draft <path> (--input-file <path> | --stdin) [--client-nonce <uuid>] [--wait]
chat workflow publish <path>
chat workflow status <run-id> [--project <project>]
chat workflow cancel <run-id> [--project <project>]
chat workflow retry <run-id> --step <step-key> [--project <project>] [--client-nonce <uuid>]
chat workflow feedback --stdin
chat workflow feedback <run-id> --step <step-key> [--project <project>] [--attempt N] --stdin
chat workflow complete --stdin

# Trigger
chat trigger create --project <project> --stdin
chat trigger list --project <project> [--cursor <cursor>] [--limit N]
chat trigger preview --project <project> --stdin
chat trigger show <trigger-id> --project <project> [--cursor <cursor>] [--limit N]
chat trigger edit <trigger-id> --project <project> --stdin
chat trigger run <trigger-id> --project <project> --state-version N
chat trigger pause <trigger-id> --project <project> --state-version N
chat trigger resume <trigger-id> --project <project> --state-version N
chat trigger delete <trigger-id> --project <project> --state-version N

# Results: optional reporting during the final Asset Wrap-Up turn
chat result list --session <session-id> --project <team/project> [--kind <kind>] [--last N] [--before <cursor>]
chat result list --target <ref> --project <team/project> [--last N] [--before <cursor>]
chat result list --used-by <ref> --project <team/project> [--last N] [--before <cursor>]
chat result show <result-id> --project <team/project> [--last N] [--before <cursor>]
chat result report --stdin [--project <team/project>]
chat result report --retry-stdin

# session (delegation and finishing your own)
chat session list --project <project> [--last N] [--before <cursor>]
chat session run [--agent <agent>] --project <project> [--repo <owner/repo>] [--runtime <claude-acp|codex-acp>] [--config <ID=id:VALUE|boolean:BOOL>]... [--attach <path>]... [<msg> | --stdin]
chat session read <session-id> --project <project> [--last N] [--before <cursor>] [--match <text>]
chat session send <session-id> --project <project> [--resume | --cancel-current-turn] [--attach <path>]... [<msg> | --stdin]
chat session compact [<session-id> --project <project>] [--request-id <uuid>]
chat session finish

# Feedback and reporting
chat skill feedback <skill-name> ("feedback" | --stdin) [--location <path-or-section>] [--suggestion <text>]
chat report ("message" | --stdin) [--level error|warning|info] [--context '{"key":"value"}']
```

- Omitting `--agent` in `chat session run` starts a new session of yourself; specifying it starts a session of another agent in the same project (delegation; [Sessions](/en/docs/sessions))
- A `chat` project argument accepts a name in the current session or a same-team `<team>/<project>` qualified form. Another team or a project outside session scope is rejected
- Mentions use the exact project-member name `@<agent>.<owner>`; an unknown target warns. A slash command goes at the start of the prompt and is not a flag
- `chat session finish` is not immediate termination. After the current turn it runs one asset wrap-up and returns `repo_handoff_preview`: a local read-only snapshot for the configured workspace repo and the required agent repo. It reports dirty count, Session commit count, whether the local remote-tracking ref contains HEAD, and a closed failure code. It does not fetch or query a remote, so `target_containment_not_observed` means only that local containment was not confirmed; it does not prove that the work is unpublished or invisible to others.
- `chat session compact` compacts the current or target session after the current turn and before an ordinary follow-up. Retry an ambiguous failure with the same `--request-id`. If the runtime does not expose compact, the command errors; the hint is to save durable context, `session finish`, then start a fresh session. The command itself does not finish ([Sessions](/en/docs/sessions))
- `--type` is for root posts only. It cannot be combined with `--reply-to`
- `chat project create` creates a child of the current parent Project from its current Lead Session. It requires `--parent <parent>`, `--lead`, and a Brief through `--stdin`. Choose the child Lead from the parent Project's active members
- Run `chat wait --all` with `--project <team>/<project>`, or from the current Project directory, with 1–100 explicit targets in total: direct child Sessions, top-level Workflow Runs started by the source agent, or Project Asks, all in that Project. Repeat each flag as needed. Keep the accepted wait ID and end the turn. While waiting, do not finish, poll, re-register, or send a manual follow-up
- `chat wait show <wait-id>` is read-only; it neither resumes work nor blocks. One continuation is accepted after all targets settle. Cancellation or failure can be settled and does not mean success. See [Sessions](/en/docs/sessions) for checking acceptance and results
- For G2 recovery reads, `chat wait show <wait-id> --project <team>/<project>` and `chat workflow status <run-id> --project <team>/<project>` accept an explicit Project; omitting it uses the cwd form above. Check each installed command’s `--help` for support. Asks require an explicit Project, as in `chat ask show <team>/<project> <ask-id>`, rather than relying on cwd. Read a Session with `chat session read <session-id> --project <team>/<project>`. The owner-local `aachat session logs <session-id> --from-start` does not accept `--project`. These are reads, not notification redelivery or work retries ([recovery](/en/docs/troubleshooting))
- `chat ask wait --timeout` is required and at least 1 second. This bounds a wait within the current turn; it does not register a continuation like `chat wait --all`. Timeout means the Ask is still open. Do not tight-poll; later read it with `ask show` / `ask list` / `chat read`
- Session `run` / `send` may be attachment-only. Timeline `chat send` has no attachment flag; use WebUI attachment or Project Media
- When `--via` is omitted, the value of the environment variable `AA_VIA` is used
- `chat media --download` requires a supported CLI/API and Session coverage with write access. Pass `media.id` from the ready list or its canonical URL, without listing flags. See [Media](/en/docs/media) for reading `downloaded.path` from success JSON and handling failures. Do not republish the downloaded copy.
- `chat media --delete` takes back a published Media. Pass the `media.revision` from the same list to `--revision`, and do not combine it with listing flags or `--download`. Deletion is irreversible and the canonical URL stops resolving. A Media that a current Shared Document or Project HTML references is refused with `media_in_use`; remove those references first.
- Defaults for `--last N`: `read` / `inbox` / `mentions` / `find` are 20, `thread` / `session read` are 50, `media` is 30 (range 1-50). Others are 1-100

### Resolve the Project and interpret acceptance

Workflow `init/list/show/runs`, published `run`, `status/cancel/retry/feedback` accept `--project`; otherwise they resolve cwd. `runs` without a slug lists Runs across Workflows in that Project. `publish` and `run --draft` select the Project from the canonical Draft path; draft run conflicts with `--project`. `validate` must run from the matching Project directory and **calls the server** to validate its Draft Bundle. It is not an offline check. `complete` targets only the current Workflow Attempt; never substitute Session finish. Feedback accepts plain text on stdin, using the current Attempt or an explicit Run/Step ([Workflows](/en/docs/workflows)).

`run --wait` and `chat wait --all` register durable continuation and return without waiting in the process. Keep the accepted ID and end the turn; inspect settled targets on continuation, since settled includes failure/cancellation. Reuse a client nonce only for the exact same request after uncertainty. Do not send changed input under the same nonce.

See [Workflows](/en/docs/workflows) to inspect the published Revision’s Steps and dependencies with `workflow show` before starting. Show does not start a Run.

Every Trigger command requires `--project`. Use current `state_version` from show/list for run/pause/resume/delete; edit includes it in its complete JSON input. Pass the returned `next` to `--cursor` for lists and occurrence history. Read the [complete Trigger JSON and recovery procedures](/en/docs/triggers) before creating live automation.

Message search (find) excludes the first user prompt dispatched to a Trigger/External Session. This does not exclude ordinary human posts or the first message of every Session, and the exclusion does not apply to mentions. If a launch instruction is missing from search, open the target Session's transcript to inspect it ([Sessions](/en/docs/sessions)).

`chat send` and `chat read` can also select their Project with `--project` instead of the positional argument; Ask commands accept the same alternative. Session `list` defaults to 50 (max 100), unlike public `aachat session list` (20). Session `read --match` searches retained text such as saved conversation and tool inputs in the specified Session and Project as literal excerpts, with no next-page cursor. New permanent history does not store tool output; neither search nor ordinary reads can recover it. See [Sessions](/en/docs/sessions) for the storage boundary, preserving results, and search window and limits. `--resume` exists only on agent `chat session send` and conflicts with cancellation. The public bounded decision/submission examples and turn-ID interpretation are in [Sessions](/en/docs/sessions).

Record a delivery receipt only after native Git push or PR creation succeeds; the receipt does not perform either operation. Follow the complete [Code Delivery](/en/docs/code-delivery) sequence and retry only the receipt if native delivery already succeeded.

## aachat-mcp

`aachat-mcp` is automatically connected as an MCP server to sessions started by `aachat up`. Agents inside sessions need no manual setup. It provides only these 3 tools:

- `aachat_concept_reviews` — read reviews for the current published Concept Revision
- `aachat_concept_review` — post an endorse or concern review on a Concept Revision
- `aachat_concept_removal_propose` — ask a human to archive a current Concept

Discover and read current Concept and Entity state from YAML under `aachat/teams/<team>/{concepts,entities}`. After editing a resource, use `chat registry check / plan / submit`; use `chat registry refresh` to restore server truth. Search messages with `chat find`. For detailed types and lifecycles, see [Concept Registry](/en/docs/concept-registry) / [Company](/en/docs/company).


---

# Troubleshooting — isolate by symptom

> The agent ignores project context, changes do not take effect, sessions do not start, and failures in auth, startup, sync, and clone. For each symptom, the order of checks and the fix.

# Troubleshooting — isolate by symptom

For each symptom, this page gives the order of checks and the fix. When a user reports a problem, walk the check steps of the matching symptom from the top. If no symptom matches, go to `aachat support` at the end of the page.


## Find the recovery procedure by symptom

| Symptom | Next read and action |
|---|---|
| Workflow Step failed, or Run needs attention | Read the Run's available actions and failed Attempt before retry/cancel: [Workflows](/en/docs/workflows) |
| Trigger did not start, paused, or conflicts | Inspect occurrences and current state version; reconcile an unknown result before resending: [Triggers](/en/docs/triggers) |
| Database absent, migration stale, or SQL result too large | Read schema/errors, reconcile accepted writes, reduce columns/page size: [Database](/en/docs/database) |
| Desktop startup/update stopped | Check the app and CLI versions separately and follow the displayed recovery: [Desktop](/en/docs/desktop) |
| Share expired, URL lost, or recipient cannot open it | Check scope, expiry and revocation; Media URLs alone are not public shares: [Sharing](/en/docs/sharing) |
| Media rejected despite a small file | Check dimensions, page count, duration and format as well as bytes: [Limits](/en/docs/limits), [Media](/en/docs/media) |
| Agent stopped but changes seem missing | Compare repository HEAD, native delivery, receipt and local observation: [Code Delivery](/en/docs/code-delivery) |
| Runtime config rejected | Reread the offered profile and typed options; inspect acceptance before retry: [Agents](/en/docs/agents) |
| Skill Ledger source or recent history missing | Use Reload and check the Agent's projected source. Cached source can be omitted to fit the inventory report; recent feedback/change windows do not include all history. Missing source or an empty recent list does not prove deletion or no usage: [Skills](/en/docs/skills) |


## Cannot retrieve existing Media inside a Session

Check `chat --version` and `chat media --help` for download support first. If unsupported, stop and confirm a supported version. For `media_unavailable`, check the same Project’s ready list, target, and readiness. For `media_download_failed`, read `reason`, retry once, and report a repeated failure with `chat report`. Without success JSON, do not guess the contents or treat a remaining file at the same path as proof of this attempt’s success. Check API authentication and permission errors separately from download failures. Follow the [Media prerequisites, download, and reading steps](/en/docs/media), keep the canonical reference, and do not republish the copy.

## Diagnostic commands first

Two diagnostic commands are the entry point for isolation.

- `aachat doctor` — environment and auth diagnostics. Shows problematic items as `✗` with fix instructions
- `aachat status` — connection to the server and the state of `aachat up` (the daemon). Includes the Launch Report (`daemon.launch_report`) and document mirror state

## Hand diagnostics for the failed operation to support

Record the operation time with its timezone, Team/Project, existing IDs such as the target Session, Run, or invocation, the CLI or app version, and the expected and actual results. When `chat` fails inside a Session, read its stderr JSON and exit status as well as stdout, then use `error` and any `hint` or `commands` to choose the relevant recovery procedure ([CLI output streams](/en/docs/cli)). Help/version output is text. For a write or launch with an unknown outcome, check existing acceptance and target state before following that operation's retry procedure. Do not repeat the operation just to obtain more diagnostics.

In supported `chat` versions, start with `diagnostic` in the failure JSON. For a Web API failure, use the browser's Network panel, when available, to inspect the relevant request's HTTP status and `X-Aachat-Request-Id` response header. Diagnostic fields absent from the screen may not be obtainable. Select the necessary evidence instead of sharing entire logs containing secret tokens, cookies, or request bodies.

| Information actually obtained | Meaning and use |
|---|---|
| `diagnostic_id` | A clue for finding a diagnostic record. It is not a Session ID, idempotency key, or completion receipt. |
| `context.http_request_id` / `context.server_http_request_id` | Correlation IDs for the client's HTTP attempt and the server response, when obtained. A new HTTP attempt gets a new ID; server correlation can be missing or have a different ID. Web diagnostics may omit a separate server ID when it is the same. Keep the actual values and where they came from. |
| `context.build_sha` / `missing` | `unknown`, `dirty`, or `build_unverified` leaves the running build unverified. Keep missing-data reasons such as `server_correlation_unconfirmed`. `missing` can appear inside context or directly under the diagnostic; do not interpret absent fields as success or absence of a fault. |
| `context.code_location` | `failure_site` identifies a failure location, `operation_boundary` an operation boundary, and `capture_only` a recording location. The location alone does not establish the root cause. |

Record `chat --version` or `aachat --version`, and report fields you could not obtain. A CLI version does not establish the API, Web, or long-running runtime version. A diagnostic ID proves neither delivery, successful work, recovery, nor receipt by Sentry.

The stderr read through the [Session log procedure](/en/docs/cli) is separate from the long-running runtime's diagnostic log. If existing server stdout or the configured runtime log is needed, give an authorized administrator/support the times and IDs above to request correlation. An inaccessible log is unverified, not empty; neither complete logging nor a retention period is guaranteed. See [Developer API](/en/docs/developer-api) for HTTP correlation and redirect failures. After repair, verify the original operation's result separately.

## New Project has a disabled Create button or no Lead candidates

A Name alone is insufficient. Check **Name, Lead, and Brief**. Names use 2–30 lowercase letters, numbers, or hyphens; `stream`, `dm`, and `repo` are reserved. The optional description cannot replace the Brief.

If no Lead is available, check the team and agents you own. Through New Project or the human CLI, choose an active human member of the team or an agent you own. A child Project requires an active parent where you are an Admin or the current Lead. The chosen Lead is added to the parent at creation if needed; prior parent membership is not required. Session agents using `chat project create` must instead select an active parent member from the current parent Lead Session. See [Setup](/en/docs/setup) for a first Project without a parent, and [Projects](/en/docs/projects) for detailed conditions.

If acceptance produces no response, or a network error leaves creation uncertain, check Projects for existing creation first. For an agent Lead, check the accepted Session and follow the Session startup and runtime authentication checks below before repeating the setup request. For a human Lead, check the notification, Project, and Brief, then begin the work as a human; this result does not start an agent response.

## I answered an Ask but work has not continued

Check answer saving separately from Session continuation.

1. Check for the saved answer under **Answered**, its revision, and **Change history**. Selecting an option only makes a draft; use **Save answer / Save only** to save it. Resolve any error or conflict by comparing the latest answer with the draft. Only the assignee or a Project Admin can answer.
2. Open the source Session. With a supported Web/API version, **Awaiting results** leads to the wait panel above the composer. Expand the targets and follow their links to find any unsettled Ask, Session, or Run. For **Couldn't load wait details.**, use that panel's **Retry** to reread; this is not a delivery retry. If the panel is absent or unreadable, inspect the transcript's accepted registration and wait ID. A Session agent can read `chat wait show <wait-id> --project <team>/<project>` ([CLI](/en/docs/cli)). Do not infer unregistered status from a missing panel.
3. After all targets settle, continuation acceptance may wait until the next check on a 30-second cycle. Do not poll, re-register, or add a manual send during that interval. Open **Wait completed**, if present, and inspect each result. If it remains absent after that cycle, inspect whether the source Session is `stopping` or archived and whether its agent still has Project collaborator access. **Needs attention** flags failed, attention-required, or cancelled targets, not a failure to save your answer. Follow the affected target to its results; for a failed Session, use the runtime recovery below.
4. Check notification delivery separately. **Delivery pending** means delivery is still pending; inspect the source Session state before adding work. For **Delivery failed**, expand the same notification, read the error, restore the reported condition, then use **Retry delivery** if available. It requires a `running` Session, an operable workspace, and a connected client that is not reconnecting. **Retry requires a running Session.** directs you to Session recovery, not another wait registration. **Delivery cancelled** is not delivered and offers no failed-delivery retry. For ordinary Session work, recover or replace the source, then send one new follow-up carrying the saved result links or IDs; Resume alone does not requeue the cancelled notification. For a Workflow Step, use its recovery path below. Retry delivery does not start a new Session, rerun a Workflow Step, or change the saved result snapshot.
5. When delivery proceeds, read the next turn and the result that uses the saved answer. A saved system notification, accepted retry, or accepted Resume is not proof of that result. System notifications do not support ordinary queued-message edit, remove, or **Run now** actions.
6. Saving a normal Project Ask without a registered wait does not start a new turn. If the same work needs to continue and its source is running, send the saved answers once as a manual follow-up. For stopped work, follow the recovery below. Do not try both paths while registration is unclear.

After the corresponding API, database changes, and Web UI are delivered, **Answer saved. The session will continue when all wait conditions are met.** means saved and waiting for conditions; **Chat continuation accepted** means automatic continuation was accepted. Even the latter does not prove that the agent read the answer or succeeded: inspect the source Session’s next turn and result. Missing displays do not prove there is no registered wait. **Send N answers to session** excludes automatic targets in a mixed group; a smaller count alone is not a save failure and is not a reason to resend. If you edited an answer after acceptance, check its revision in **Change history**, the current display, and the source Session’s state. Automatic delivery of the changed answer is not guaranteed (see [saving and continuation](/en/docs/projects)).

Cancellation is settled but is not approval, and a later answer change does not fire the same wait again. See [Sessions](/en/docs/sessions) for notification meaning and version conditions, and [Projects](/en/docs/projects) for answering conditions. If unresolved, preserve Project, Session, Ask and wait IDs, answer revision, continuation/delivery IDs when available, states, errors, and timestamps for investigation.

## A missing REPORT prevents Done

`project_report_required_for_completion` or “Create or update Current report, then retry completion.” means an active Project with a Lead is missing its REPORT.

Ask the current Lead to save results, verified evidence, and remaining gaps at the exact path `aachat/projects/<team>/<project>/docs/REPORT.md`. Check the synced body in **Docs**, accept the results, then have an Admin retry Done. Do not bypass the condition with an empty document, a different name such as `report.md`, or a switch to planning. If the menu itself is unavailable, ask a Project Admin to operate it.

If the same rejection persists after saving, follow “Shared Documents are not syncing” below. Preserve the Project ID, REPORT path and saved version (`row_version` if available), error code, and timestamp. See [Shared Documents](/en/docs/shared-documents) for ownership and [Projects](/en/docs/projects) for acceptance.

## The agent ignores the project's context

Symptom: responses appear to ignore the project's past decisions and outputs.

Check, in order, the paths of context the agent reads at session start. The fix depends on which one is missing.

1. **The project's PROJECT.md** — does it state the stable Purpose, Outcome, Outputs, decision principles and boundaries, curated Context Map, and Approach? If absent, or if this stable contract is stale, fix it. Do not update it with progress, assignments, handoffs, logs, or unresolved notes
2. **The Context Map and generated `index.md`** — can the agent reach the needed canonical sources through the curated links in `PROJECT.md`? For documents outside that route, use generated `index.md`, which lists the full catalog
3. **Recent dynamic context** — is the handoff available in the previous session transcript, a short project message, or a normal Shared Document? Do not move it into `PROJECT.md` ([Shared Documents](/en/docs/shared-documents))
4. **The agent repo's memory** — are the rules of thumb and knowledge that should carry across projects in the agent repo's `memory/`? If not, write them and push. They take effect from the next session

For the definition of the two layers of context an agent reads (the agent's own memory / the work context), see [Concepts](/en/docs/concepts).

## Changes to identity / skills / memory are not taking effect

Symptom: you edited the agent repo but the agent's behavior does not change.

The cause is reflection timing. Agent repo changes take effect **from the next session after committing and pushing**. They are not reflected in running sessions.

Fix: push the changes and start a new session. For the agent repo structure, see [Agents](/en/docs/agents).

## A session does not start

Symptom: a session does not begin from `session run` or a request via the target chip. Check these three conditions in order.

1. **Is the project status `active`?** Only active projects can run sessions. Check the status display in the WebUI project header
2. **Is the agent a member of that project?** The agent in `session run` is resolved as a project member. If not a member, add it to the project
3. **Is `aachat up` running on the agent owner's side?** The agent's runtime runs on the owner's machine. Check whether it is online via the WebUI agent display or `aachat agent list`. An agent shown as `dormant` is excluded from the launch targets of `aachat up`; restore it with `aachat agent update <name> --no-dormant`

## A session appears stuck

Symptom: the session started but the response is not progressing.

- **Check for a pending Permission.** The agent waits for execution approval before high-impact operations and keeps waiting until it gets a response. Check whether an approval dialog is showing in the WebUI workspace panel and choose allow or deny
- **Check whether you only sent an @mention.** The exact `@<agent>.<owner>` is a notification, not a trigger for session execution. Address the agent via the target chip or use `session run` ([Sessions](/en/docs/sessions))

## A session stopped or failed midway — what remains

Even if a session terminates abnormally (`failed`) or stops midway, the work done so far is not lost.

- **The conversation record remains.** The session record and transcript are stored on the server and can be checked anytime with `aachat session read`
- **What was left in the project becomes the next input.** The deliverables and decisions the session left in Shared Documents and the Timeline can be read as-is by the next session (the same agent or a different one) to continue from there

Check the intermediate state. If the same work is resumable, an agent can explicitly use `chat session send <session-id> --project <project> --resume "follow-up instruction"`. Replace `<session-id>` and `<project>` with the target Session and Project, and supply the follow-up instruction text. If it cannot be restored, or the work is new, hand the needed results to a new Session. See [Sessions](/en/docs/sessions) for the conditions.

A runtime prompt execution error can leave the Session `failed`; it is distinct from failure to deliver a wait notification. First read the saved transcript and inspect `aachat session logs <session-id> --from-start` on the owner's machine. After resolving the reported runtime cause, check the Session's Resume eligibility and any refusal reason. For the same work in an eligible `stopped` or `failed` Session, the Session owner can use the WebUI **Resume** action; an eligible running agent can use the command above. A non-owner Project Admin or collaborator must involve one of them. Then confirm runtime reconnection and the next result. Wait through `starting` or `stopping`; do not repeatedly resume. Archived Sessions or unrestorable workspace/configuration/Project coverage cannot use this path.

For a **Workflow Step**, open its Run and use Workflow retry only for a Step offered in `available_actions.retry_steps`. A failed Published Workflow Step requires opening the child Run and retrying its failed inner Step. This creates a new Attempt; generic Session Resume is not allowed. Inspect the new Attempt and output before treating recovery as successful ([CLI](/en/docs/cli)).

### Before resending work after a runtime restart

1. Open the original Session and read its accepted turn and saved transcript. If it is `starting`, recovery may be in progress; check the next state and response before repeating run/send.
2. Inspect result documents, the working tree, delivery such as pushes and PRs, and external operation results to identify work already performed. Accepted work may be redelivered conditionally, so external operations are not guaranteed to occur only once ([recovery conditions](/en/docs/sessions)).
3. If recovery stops, give an administrator the original Session/Run ID, accepted turn, time, Project state, error code/body, API/runtime versions, and existing results. For refusals such as 403, check the target Project and permissions and reread state before repeating an operation. Only restorable ordinary Sessions use the Resume steps above; terminal Workflow Attempts follow the Run's offered retry or new Run conditions.

An empty search does not prove that work disappeared. Inspect Trigger/External launch instructions excluded from find in the original Session's transcript. An empty successful `read --match` response means no match in the specified Project and window; 403, 404, and timeout are read failures. Check the [search scope and excerpt limits](/en/docs/sessions).

If tool output is absent from history, check your version and the [Session storage boundary](/en/docs/sessions). New permanent history does not store tool output. Missing output, an empty result actually returned by a tool, and a failed history read are different; absence alone establishes neither execution success nor failure. Reconcile saved status and the final response with actual artifacts such as Shared Documents. Do not repeat writes or execution solely to fill the gap. If you need help, use the support steps above and provide the Session ID, time, versions, diagnostics actually obtained, and information you could not obtain.

## I want to see the logs

The command to use and the place to look differ by what you want to know.

| What you want to know | Command | Stored at |
|---|---|---|
| Conversation content and responses (transcript) | `aachat session read <session-id> --project <project>` | server |
| Execution errors and runtime stderr | `aachat session logs <session-id> --from-start` | local (`~/aachat/.run/logs/`) |

Find the session ID with `aachat session list --agent <name>`.

## Authentication fails

Symptom: the CLI returns an authentication error. Check the state first.

```bash
aachat auth status
aachat doctor
```

The two `✗` items `aachat doctor` commonly shows are the following; follow the instructions attached to the `✗` line.

- `✗ User JWT: expired` — the aachat sign-in has expired. `aachat auth login` issues a short-lived JWT from the local `gh` token, so if `gh` is authenticated it completes non-interactively
- `✗ GitHub auth: not logged in` — the GitHub CLI is unauthenticated. `gh auth login` or `gh auth refresh -s repo,read:user` must be run by a human by hand

## `aachat up` fails to start or dies midway

Launch results are recorded in the Launch Report.

```bash
aachat status                    # Look at daemon.launch_report
cat ~/aachat/.run/logs/up.log    # The === Launch Report === section
```

`[failed]` lines carry an `action:`; follow that instruction. Rough guidance by category:

| Category | Where to look |
|---|---|
| `[failed] ... GIT` | Connection to GitHub, auth, branch configuration |
| `[failed] ... AUTH` | `gh auth status` |
| `[failed] ... PREREQ` | The instructions from `aachat doctor` |

Workspace cleanup and runtime readiness are separate:

- `[started]` with `workspace_warning` means the runtime is ready. Historical workspaces were preserved for maintenance; run `aachat doctor` for every path and repair step.
- A failed authoritative session snapshot or orphan reconciliation keeps only that agent offline because resumable workspace protection cannot be proven. Restore API access and rerun `aachat up`; do not delete workspaces to bypass it.
- If a new session collides with a preserved workspace, only that session fails. Inspect the session error and `aachat doctor`, preserve any local work, then repair or remove only the reported workspace.

`aachat status` exposes the maintenance counts at `daemon.launch_report.workspace_maintenance` and emits the `session_workspace_maintenance` warning without turning it into a readiness blocker.

## Environment variables do not reach the agent

Symptom: API keys and the like do not arrive, and the agent reports "no key".

Check the per-agent env lines in the Launch Report.

```bash
cat ~/aachat/.run/logs/up.log    # The env: provider=... loaded=N missing=N denied=N line
```

- `env_loaded` — variables that were actually passed
- `env_missing` — variables declared in `environment.yaml` for which no value was found
- `env_denied` — variables that have a value but are not approved to be passed (deny-by-default)
- `provider_unavailable` — the provider itself could not be read. Check the `.env` path and permissions, or the Infisical CLI, login, and `env.toml` configuration

Use the variable names shown under `missing` / `denied` to fix the configuration, then restart `aachat up`. For the full picture of secret handling, see [Environment](/en/docs/environment).

## Shared Documents are not syncing

Symptom: a document an agent should have created is not visible, or edits are not reflected.

```bash
aachat status
```

If `daemon.host_mirror.state` or `daemon.workspace_mirror.state` is `error`, the offending files are listed in `error_files[]`. Do not edit the auto-generated `_errors.md`; fix the offending files it points to. If fixing them does not recover, restart `aachat up`.

As a premise, the source of truth for Shared Documents is the server, and the local `aachat/projects/` is a projection. Sync happens only while `aachat up` is running ([Trust Boundary](/en/docs/trust-boundary)).

## A Discover clone fails

Symptom: an error like the following at clone time.

```
Could not access repository '<owner/repo>'.
  Check that the repository exists and is public (or you have access).
```

1. Has the source agent's repo become private? If so, pick another published agent or get access from the author
2. Have you hit the GitHub API rate limit (`gh api rate_limit`)? If so, wait and retry
3. Are the scopes (`repo`, `read:user`) in place (`aachat doctor`)? If missing, run `gh auth refresh -s repo,read:user`

## Skill projection or precedence is unexpected

The Launch Report may report a workspace / Platform collision, missing `SKILL.md`, symlink / special file, or non-UTF-8 path. Some same-name cases intentionally shadow a skill instead of failing setup.

1. Make each Team / Agent skill a normal file at `.agents/skills/<name>/SKILL.md` or `.claude/skills/<name>/SKILL.md`. Do not use root `skills/`
2. If a workspace / Team skill collides with a Platform skill such as `aachat-session`, rename the workspace skill; this collision fails setup
3. If an Agent skill has a Platform name, setup succeeds but the Platform version shadows it. Rename the Agent skill if the custom version was intended
4. If workspace / Team and Agent have the same non-Platform skill name, the workspace intentionally shadows the Agent skill. Rename one if that is not intended
5. Replace symlinks, directory-only skills, special files, and invalid names with ordinary UTF-8 files, commit / push, and start a new session

Sources and precedence are in [Skills — Sources of Truth and Improvement History](/en/docs/skills).

## Claude workspace settings fail prepare

The Claude runtime preserves hooks / MCP / plugins / commands / custom allow-deny settings from the workspace repo and merges aachat's required permissions. aachat does not directly modify tracked settings.

When an explicit repo deny conflicts with a required permission, prepare fails instead of silently bypassing it. Inspect the permission in the Launch Report, then intentionally change the repo policy or select a suitable runtime / repo and start a new session.

If immediate Shared Document write-validation feedback is missing under Codex, that is a known limitation. Run `aachat doc check <path>`, or use Claude when inline hook feedback is required.

## An External Session Run is rejected, duplicated, or fails to start

First inspect the HTTP status and the response's `status`, `session_id`, and `web_url`.

1. For 401 / 403, check the token value, expiry, and whether it was rotated or revoked. Rotate rather than reusing a token that may have leaked
2. For a membership rejection, verify that the project is active, the credential creator and target agent still hold the required project roles, and the agent owner has not changed
3. For an idempotency conflict, check whether the same key was reused with different text, metadata, or execution context. Retry the same work with the same request; use a new key only for new work
4. If startup fails after acceptance, inspect the returned session and the owner's Launch Report, restore the runtime, then check the existing invocation before retrying

[External Session Runs](/en/docs/external-session-runs) is canonical for credentials and requests.

## Project HTML was updated but the display is old

If the serving-snapshot rebuild after source sync fails, the previous healthy snapshot keeps serving. Inspect rebuild status and error in the HTML catalog, fix the source file, and rebuild. Do not treat successful `aachat up` sync alone as proof that display changed ([HTML](/en/docs/html)).

## Archive is blocked or does not complete

**Before acceptance:** Check that you are a Project Admin and the Project is in planning, active, or completed. For active children listed in the confirmation, review the results and mark them Done, reparent them, or check their effects and archive them. If a Workflow Session also covers other Projects, finish its work and reread the confirmation. If the confirmation has changed, reopen it and check the current counts and targets. If choosing Archived in the header or another route returns “Archive confirmation required”, open Archive from Settings.

**When reparenting is rejected:** `project_reparent_status_conflict` means the child is not planning or active, or the new parent is not active. Restore the child if needed and choose an active new parent. You also need Admin access to both the old and new parents, and the relationship must not create a cycle. Separately, `Archive is in progress.` rejects reparenting when the child or new parent is being archived. Correcting the status condition does not remove this restriction. Confirm that Archive has finished, then check the statuses and destination again.

**After acceptance:** Reopen the Project and check Remaining Runs and Sessions waiting to stop under **Archive in progress**. An ordinary Session still executing does not by itself indicate an Archive failure. If **Could not complete Archive** appears, read the error and inspect the indicated Run or Session. After checking the problem, an Admin can choose **Retry** on the same Project. Retry acceptance is not completion either; confirm that the Project becomes Archived. If progress cannot be loaded, retry the read rather than treating it as completion.

Do not try to bypass an Archive in progress through status changes, deletion, or reparenting. If it remains unresolved, give an administrator the Team and Project, time, status, remaining Run and Session counts, error code and message, indicated IDs, and versions in use. Do not include credentials. Restoring the Project does not automatically restore cancelled work ([Projects](/en/docs/projects)).

## Project deletion failed

Project deletion is asynchronous; the WebUI shows Deleting / Deletion failed / Retry. On failure, inspect the error and resume from Retry on the same project. Do not create a replacement project with the same name to bypass the operation. Use archive rather than delete when recovery may be needed ([Projects](/en/docs/projects)).

## When nothing above resolves it

Start interactive support.

```bash
aachat support
```

Describe the symptom as-is, and it walks interactively from log investigation to repair.

## Related pages

- Session specification (state transitions, records, workspace, delegation): [Sessions](/en/docs/sessions)
- Agent repo structure and reflection timing: [Agents](/en/docs/agents)
- Secrets and the environment variable mechanism: [Environment](/en/docs/environment)
- Skill collisions: [Skills — Sources of Truth and Improvement History](/en/docs/skills)
- Term definitions: [Glossary](/en/docs/glossary)


---

# Glossary

> A one-page index of one-line definitions for aachat terms. The basis and details of each definition live in the referenced canonical pages.

# Glossary

This is the index of aachat terms. When asked what a term means, answer immediately with the definition here, and use the referenced page as the basis for details. The order is not alphabetical; closely related terms are placed next to each other.

For relationships, read [Concepts](/en/docs/concepts); for first use, [Setup](/en/docs/setup); for a failure, [Troubleshooting](/en/docs/troubleshooting).

## Worldview

| Term | Definition | Details |
|---|---|---|
| **agentic company** | A company where AI agents understand the company, share roles with humans, carry company work from objectives through to verified results, and reuse capabilities gained from that work in future work | [Concepts](/en/docs/concepts) |
| **Agentic Company Builder** | aachat's primary concept: build and develop company structures and capabilities that can take on larger pieces of work | [Concepts](/en/docs/concepts) |
| **Company as Code** | A way for humans and agents to read, change, verify, and improve company structures such as Projects and Workflows | [Concepts](/en/docs/concepts) |
| **Agent as Code** | A way to build and develop the knowledge, judgment criteria, and skills of agents working as employees in repositories | [Concepts](/en/docs/concepts) |
| **Agent work becomes company assets** | Preserving work outcomes, decisions, and reusable capabilities in the company for use in future work | [Concepts](/en/docs/concepts) |

## Places and participants

| Term | Definition | Details |
|---|---|---|
| **team** | The unit that shares a purpose and assets. Public, private, and personal teams differ in visibility and joining behavior | [Teams](/en/docs/teams) |
| **project** | The place of work inside a team. Three kinds: `project` / `stream` / `dm`; do not mix their uses | [Projects](/en/docs/projects) |
| **stream** | The team-wide announcement and casual channel. Human-only, undeletable, one per team. Agents cannot join, read, or be mentioned in it. Make requests to agents in a project | [Projects](/en/docs/projects) |
| **dm** | A 1:1 project between you and one agent (`dm:<agent>.<owner>`). Created automatically when the agent is brought in | [Projects](/en/docs/projects) |
| **project status** | The project's state. Four values: `planning` / `active` / `completed` / `archived`. Session execution, follow-ups, and participation — plus viewing the timeline and Shared Documents — are possible only in `active` | [Projects](/en/docs/projects) |
| **Concept** | A Vision, Issue, or Policy the team has agreed on. Agents submit proposals (pending); humans review and accept or decline them on the Concepts screen in the WebUI | [Concept Registry](/en/docs/concept-registry) |
| **Entity** | A map of the persistent, concrete things that make up the company, scoped so building, improving, maintaining, or retiring each can be decided independently. 9 kinds; `person`/`partner`/`agreement` are sensitive and cannot be written by agents | [Company](/en/docs/company) |
| **similarity gate** | The automatic check run when a new Concept is proposed. If a similar one exists, registration is rejected with `similar_found`. Resubmit with `proceed_token` only once you've judged it to be genuinely different | [Concept Registry](/en/docs/concept-registry) |
| **sensitive kind** | Entity's `person` / `partner` / `agreement`. The server rejects registration/changes from an agent and directs it to ask a human | [Company](/en/docs/company) |
| **agent** | A member that participates in a project and works. One agent = one GitHub repo. Named `{base_name}.{owner_login}` | [Agents](/en/docs/agents) |
| **character** | The pixel-art avatar that represents an agent. It signals the agent's presence and conveys state through expressions. Color is each agent's individuality | [WebUI screens and operations](/en/docs/webui) |
| **team role** | Team-wide permissions: `owner` / `admin` / `member`. Determines authority over team settings, members, and deletion | [Teams](/en/docs/teams) |
| **project role** | Permissions inside a project: `admin` / `collaborator` / `viewer`. Agents can be Admins, but a change that would leave no human Admin is rejected | [Projects](/en/docs/projects) |
| **join link** | A link for joining a team or project. Whoever opens it joins instantly (there is no approval-wait mechanism). Can be invalidated with Rotate | [Projects](/en/docs/projects) |
| **client entry** | A dedicated entry link for external clients. Sending a request through the link provisions a project with a predefined member and agent configuration | [WebUI screens and operations](/en/docs/webui) |

## The agent's substance

| Term | Definition | Details |
|---|---|---|
| **agent repo** | The GitHub repo that is the agent's substance. Changes are made via git commit and take effect from the next session after push. No one but the owner can manage it | [Agents](/en/docs/agents) |
| **identity** | The definition of the agent's persona and role (`identity.md` at the agent repo root). Injected at session start | [Agents](/en/docs/agents) |
| **memory** | The agent's memory storage (`memory/` in the agent repo) | [Agents](/en/docs/agents) |
| **knowledge** | The agent's knowledge storage (`knowledge/` in the agent repo) | [Agents](/en/docs/agents) |
| **skills** | Reusable agent capabilities and procedures. Agent, Team, and Platform sources are projected into sessions with defined precedence | [Skills — Sources of Truth and Improvement History](/en/docs/skills) |
| **Skill Ledger** | A ledger of skill usage, feedback, change history, and metrics that informs the next improvement decision | [Skills — Sources of Truth and Improvement History](/en/docs/skills) |
| **runtime** | The engine for one Session: `claude-acp` (WebUI label: Claude) or `codex-acp` (Codex). The agent setting is only the default for future launch drafts | [Agents](/en/docs/agents) |
| **dormant** | The state of excluding an agent from `aachat up` startup targets. Reactivate with `aachat agent update <name> --no-dormant` | [Agents](/en/docs/agents) |

## How execution works

| Term | Definition | Details |
|---|---|---|
| **aachat up** | The single resident process that starts all runtimes of owned agents. If it is not running, sending a request starts no work | [CLI reference](/en/docs/cli) |
| **session** | The lifecycle of the process in which the agent is actually running. `starting → running → stopping → stopped`; abnormal termination is `failed`. Auto-stops after 60 minutes idle | [Sessions](/en/docs/sessions) |
| **turn** | One round trip within a session. Has 2 states: `idle` / `active` | [Sessions](/en/docs/sessions) |
| **workspace** | The working directory isolated per session (`~/aachat/.run/workspaces/<agent>--<sid8>`) | [Sessions](/en/docs/sessions) |
| **composer** | The message input area at the bottom of the project screen. Selecting an agent as target and sending constitutes a request, which starts a session | [WebUI screens and operations](/en/docs/webui) |
| **mention (@mention)** | Addressing an agent with the exact `@<agent>.<owner>` in a message body. A notification is delivered, but **by itself it does not start a session** | [Sessions](/en/docs/sessions) |
| **follow-up / queue** | Additional instructions sent to a running session. If sent while a turn is executing, they are queued and processed in order after the current turn finishes | [Sessions](/en/docs/sessions) |
| **scheduled follow-up** | A one-time or recurring (1-minute to 1-day interval) additional request delivered later to the same session. Created from Schedule in the thread composer | [Sessions](/en/docs/sessions) |
| **Project Trigger** | A Project automation rule that starts a published Workflow or fresh Session using exactly one of Once, Daily / weekly, Interval, or Document match | [Triggers](/en/docs/triggers) |
| **session compact** | Summarizes older context in a long session and continues under the same session ID. It does not delete the original history | [Sessions](/en/docs/sessions) |
| **External Session Run** | An entry point through which CI, a webhook, or another external system uses a dedicated credential to start a new session for a fixed project agent | [External Session Runs](/en/docs/external-session-runs) |
| **Permission** | The approval an agent requests before a high-impact operation. The agent waits on that operation until you choose allow or deny | [WebUI screens and operations](/en/docs/webui) |
| **Workspace panel** | The WebUI panel that monitors session execution in real time. Work logs, Permission responses, follow-ups, and interrupts gather here | [WebUI screens and operations](/en/docs/webui) |
| **delegation (handoff / delegation)** | An agent inside a session starting and monitoring another agent's session via `chat session run/read/send` and entrusting work to it. Conditions: the delegate is online and a member of the same project | [Sessions](/en/docs/sessions) |
| **working repository** | The GitHub repo where the agent reads and writes code in a session. Distinct from the agent repo. Determined in order: session-specified → project setting → team default | [Sessions](/en/docs/sessions) |
| **Launch Report** | The startup result report of `aachat up`. Records started / failed / dormant per agent and loaded / missing / denied for environment variables. Check via `aachat status` and `~/aachat/.run/logs/up.log` | [Environment](/en/docs/environment) |
| **environment.yaml** | The declaration of dependency packages and environment variables the agent needs (`environment.yaml` in the agent repo). Only names and purposes may be declared; writing secret values is rejected | [Environment](/en/docs/environment) |
| **env provider** | The mechanism that resolves declared environment variable values at startup and passes them to the agent. Values exist only in `~/aachat/.run/.env` or the Infisical CLI, and approval is deny-by-default per agent | [Environment](/en/docs/environment) |
| **connected repo** | A development repo connected to aachat with `aachat init`. External agents such as Cursor and Claude Code can operate aachat from that repo | [Connected Repo](/en/docs/connected-repo) |

## Messages and notifications

| Term | Definition | Details |
|---|---|---|
| **Project Timeline** | The project's chronological view. In the WebUI, messages and Asks flow here. Documents are discovered in the Documents surface; sessions in the Work Panel. CLI `project read` still mixes document / session lifecycle into `items[]` | [Projects](/en/docs/projects) |
| **Asks** | The mechanism by which an agent hands a decision back to a human. A question, optionally with choices, is placed in the Project; humans answer in the WebUI or public CLI. An Ask is immutable; answers accumulate as revisions | [Projects](/en/docs/projects) |
| **Inbox** | The list of unhandled incoming context (unread notifications and messages) | [WebUI screens and operations](/en/docs/webui) |
| **via label** | A free-form label indicating which client sent a message (e.g. `cursor` / `claude-code`). Attached with the `--via` flag | [CLI reference](/en/docs/cli) |
| **Home** | The screen that opens right after login (`/home`). A cross-team overview of agent activity, joined projects, teams, and notifications addressed to you (Feed) | [WebUI screens and operations](/en/docs/webui) |

## Deliverables and sharing

| Term | Definition | Details |
|---|---|---|
| **Shared Documents** | The canonical, non-flowing deliverables and knowledge tied to a project. Put long research results and specs here, not in messages. The canonical copy is stored on the server | [Shared Documents — source of truth and projection, the document contract](/en/docs/shared-documents) |
| **projection** | The local projection of Shared Documents (the `aachat/projects/` directory). Bidirectionally synced only while `aachat up` is running. The server is canonical; local is the projection | [Trust Boundary](/en/docs/trust-boundary) |
| **kind** | The type of a Shared Document. The `_aachat:` block in `_template.md` can define its schema and scaffold | [Shared Documents — source of truth and projection, the document contract](/en/docs/shared-documents) |
| **WikiLink** | A reference link between Shared Documents. Only the full-path form `[[aachat/projects/<team>/<project>/docs/<kind>/<id>.md]]` is valid | [Shared Documents — source of truth and projection, the document contract](/en/docs/shared-documents) |
| **Documents** | The list and reading surface for Shared Documents — the human discovery surface for create/update. Document cards do not appear on the main timeline | [WebUI screens and operations](/en/docs/webui) |
| **preview_fields** | A per-kind setting specifying which fields the activity / document list API includes in its compact preview, and in what order | [Shared Documents — source of truth and projection, the document contract](/en/docs/shared-documents) |
| **Project HTML** | The mechanism for viewing and sharing agent-built HTML deliverables (`aachat/projects/<team>/<project>/html/`, entry point `index.html`). Its JavaScript executes in each member or public-share viewer's browser | [HTML](/en/docs/html) |
| **share token / share link** | A time-limited, read-only URL for viewing a Shared Document or project context without logging in. Can be revoked | [WebUI screens and operations](/en/docs/webui) |
| **Project Media** | The server-stored area that publishes finished images, videos, and PDFs as project assets. Publishing happens by placing files in `media/`, and items are referenced by canonical URL (`https://aachat.io/m/<uuid>`). `--attach` attachments are not published here | [Media](/en/docs/media) |
| **mindmap / brainstorm blocks** | Structured fenced blocks writable in chat messages and shared documents. Used for organizing thinking / diverging on ideas. Rendered read-only | [Markdown blocks](/en/docs/markdown-blocks) |

## Catalog

| Term | Definition | Details |
|---|---|---|
| **Discover** | The catalog for public agents, skills, teams, and Project Templates. Find and adopt them here; publish eligible assets here | [Discover](/en/docs/discover) |
| **clone** | Duplicating and registering an agent found in Discover as your own private repository | [Discover](/en/docs/discover) |
| **submit (publish)** | Publishing your own agent to Discover | [Discover](/en/docs/discover) |
| **kind template** | The unit for publishing and adopting a Shared Document kind definition. Distinct from a Project Template | [Templates](/en/docs/templates) |
| **Project Template** | A reusable project configuration applied when creating a new, independent project | [Templates](/en/docs/templates) |

## CLI

| Term | Definition | Details |
|---|---|---|
| **aachat (CLI)** | The CLI with which humans and external agents operate teams, agents, projects, and sessions | [CLI reference](/en/docs/cli) |
| **chat (CLI)** | The agent-only CLI inside sessions started by `aachat up`. Not for use outside a session | [CLI reference](/en/docs/cli) |
| **aachat-mcp** | The MCP server automatically connected to `aachat up` sessions. Provides only `aachat_concept_reviews`, `aachat_concept_review`, and `aachat_concept_removal_propose` | [CLI reference](/en/docs/cli) |
| **Team Registry projection** | Typed YAML under `aachat/teams/<team>/{concepts,entities}` where session agents discover, read, and edit current Concept and Entity state. Changes are validated and submitted with `chat registry` | [CLI reference](/en/docs/cli) |

## Automation and verification

| Term | Definition | Details |
|---|---|---|
| **Workflow** | Typed Steps connected by dependencies, reusable within a Project | [Workflow guide](/en/docs/workflows), [Definition reference](/en/docs/workflow-reference) |
| **Draft / Revision / Published** | Editable Bundle / immutable saved definition / pointer used for new published Runs | [Workflows](/en/docs/workflows) |
| **Run / Attempt** | Execution with fixed Revision and input / one execution of one Step | [Workflows](/en/docs/workflows) |
| **Decision Step** | Workflow Step that creates a human Ask and pins the answer used downstream | [Workflows](/en/docs/workflows) |
| **Project Database** | Server-managed structured Project rows; agents use schema, migrations, and SQL, humans browse read-only tables | [Database](/en/docs/database) |
| **Meeting** | Team-level title, time, participants, and notes, distinct from a Project document | [Meetings](/en/docs/meetings) |
| **Lead** | Project member responsible for coordinating the work and maintaining REPORT; distinct from permission role and Agent ownership | [Projects](/en/docs/projects), [Permissions](/en/docs/permissions) |
| **delivery receipt** | Record of a successful native push or PR creation at a specific repository and HEAD; not proof of merge or deployment | [Code Delivery](/en/docs/code-delivery) |
| **local observation** | Read-only snapshot of local repository state; it does not fetch or prove remote publication | [Code Delivery](/en/docs/code-delivery) |
| **capacity limit** | A bound on bytes, rows, dimensions, duration, or execution input; units depend on the surface | [Limits](/en/docs/limits) |
| **public read share** | Revocable access to a document or wider Project context for anyone holding the link | [Sharing](/en/docs/sharing) |
| **API credential** | Identity and scope used by an integration; not interchangeable with runtime provider authentication | [Developer API](/en/docs/developer-api) |
| **Desktop** | macOS launcher and updater that starts the local CLI runtime and opens the WebUI | [Desktop](/en/docs/desktop) |


---

# Workflows — from a Draft to a result

> Create, validate, publish, and run a Workflow; read typed results, answer decisions, and recover failed Steps.

# Workflows — from a Draft to a result

Use a Workflow when the same sequence of agent work, human decisions, and typed handoffs will run more than once. Dependencies determine when Steps become ready. For a one-off request, start a normal [Session](/en/docs/sessions). To start a published Workflow at a future time or on a document condition, use a [Trigger](/en/docs/triggers).

## Before you begin

Choose an active [Project](/en/docs/projects), a collaborator or admin who can change it, and active collaborator/admin agents for the Session Steps. The execution owner's machine needs an available aachat runtime and the selected coding-agent Runtime configured. A valid definition alone does not make an offline runtime available. See [Setup](/en/docs/setup) and [Environment](/en/docs/environment).

The `chat` commands below are for an agent inside a running aachat Session with access to the Project. Ask that agent to author the Workflow if you are using WebUI. They are not commands for an unauthenticated terminal. Replace `<team>/<project>`, agent names, and returned IDs with your actual values. A Project viewer can read content but cannot author or start work; mutations also recheck current Project and execution authority.

## What is saved

| Term | Meaning |
|---|---|
| Draft | Editable files in `aachat/projects/<team>/<project>/workflows/<slug>/`, synchronized as Project state. |
| Revision | An immutable snapshot of the definition and supporting files. |
| Published | The pointer to the Revision used for new published Runs. Publication is separate from a Draft Run. |
| Run | One execution with fixed Revision and input. Later Draft edits and publication do not change it. |
| Attempt | One execution attempt of a Step. Retrying creates another Attempt in the same Run. |

An Attempt has the exact read-only Revision Bundle at `$AA_WORKFLOW_DIR`. Read it when doing the assigned Step; never edit it or copy it over the Draft. There is no `_published` directory. Discover published definitions through `list` and `show`.

## Create a small, complete Workflow

This example takes a reader name and returns a greeting. First inspect the available agents and published names, then create the Draft identity:

```bash
chat project members <team>/<project> --runtime-profiles
chat workflow list --project <team>/<project>
chat workflow init greeting --project <team>/<project>
```

Use a new slug if `greeting` is already in use. In the generated Draft, replace `workflow.yaml` with the following and replace `writer.yourname` with the exact member name. Choose a Runtime supported by that agent. `session.runtime` and its `kind` are required; the example explicitly uses an empty configuration.

```yaml
schema_version: 1
name: greeting
description: Write a greeting for one named reader.
inputs:
  type: object
  additionalProperties: false
  properties:
    reader:
      type: string
      minLength: 1
  required: [reader]
outputs:
  greeting: "{{ steps.write.outputs.greeting }}"
steps:
  write:
    needs: []
    session:
      agent: writer.yourname
      runtime:
        kind: codex-acp
        config: {}
      prompt:
        file: prompts/write.md
    outputs:
      type: object
      additionalProperties: false
      properties:
        greeting:
          type: string
          minLength: 1
      required: [greeting]
```

Create `prompts/write.md` within the same Draft:

```text
Write one welcoming sentence for {{ inputs.reader }}.
Return the sentence in the required greeting output.

{{ aachat.step_completion }}
```

The final placeholder inserts the completion instructions for this Attempt. It must appear exactly once at the end of a Session prompt. Remove unused starter files if they are no longer needed. The schema is a closed object: `reader` is required, and undeclared input keys are rejected. The Step must return `greeting`, and the top-level mapping makes that value available as the Run result.

## Validate, try, and publish

From the workspace root, validate in the Draft's Project directory, then optionally run the Draft:

```bash
(cd aachat/projects/<team>/<project> && chat workflow validate workflows/greeting)
chat workflow run --draft aachat/projects/<team>/<project>/workflows/greeting --stdin <<'JSON'
{"reader":"Alex"}
JSON
```

Validation contacts the server to check Project agents and any published child Revision pins; it is not an offline YAML check. A validation error identifies the field or file to correct. A Draft Run starts real agent work, so use suitable input and inspect its returned Run ID with `status` before moving on. A successful Draft Run is useful evidence, but is not required for publication.

Publish the Draft and inspect its input/output contract before starting the published version:

```bash
chat workflow publish aachat/projects/<team>/<project>/workflows/greeting
chat workflow show greeting --project <team>/<project>
```

Alongside the published Revision's inputs and outputs, inspect each entry in `steps`: `key`, `kind`, and `needs`. Check `agent_name` and `runtime_kind` for Session Steps, and `workflow_slug` with the `workflow_revision_id` this Revision pins for child Workflows. Run `show` on that child slug and compare its top-level `revision_id`: equal means the parent runs the child's current published Revision, different means the parent still pins an older one. `steps` is keyed by step key; `topological_order` lists those keys in the order the Revision runs them, and that order does not guarantee serial execution of independent Steps. Show does not start a Run or expose prompt bodies, secrets, or every internal Step of a child Workflow. Start the published version after this check.

```bash
chat workflow run greeting --project <team>/<project> --stdin --wait <<'JSON'
{"reader":"Alex"}
JSON
```

Publication snapshots the files and changes the Published pointer; it does not modify the Draft files or `draft_version`. `run --wait` starts the Run and registers a durable notification for the source Session. The command returns immediately. After acceptance, the source agent ends its turn and reads the result on continuation instead of polling.

```bash
chat workflow status <run-id> --project <team>/<project>
chat workflow runs greeting --project <team>/<project>
```

A succeeded example Run returns `outputs` such as `{"greeting":"Welcome, Alex!"}`. The wording is generated, not guaranteed to be that exact sentence. Before success, `outputs` is absent. Without top-level output declarations, a succeeded Run returns `{}`. Check both the Run state and the actual result or linked artifact.

## Complete a Session Step

The agent executing the Step follows the generated completion block. In the example Attempt, after producing the actual greeting, it submits:

```bash
chat workflow complete --stdin <<'JSON'
{"outcome":"succeeded","outputs":{"greeting":"Welcome, Alex!"}}
JSON
```

If it cannot finish, it submits the cause and next action:

```bash
chat workflow complete --stdin <<'JSON'
{"outcome":"failed","error":"Required source is unavailable; restore access before retrying."}
JSON
```

Only a JSON response containing `"accepted": true` confirms acceptance of the completion intent. A timeout, terminal echo, or final chat response does not. After a transport error, retry the **exact same JSON payload** using the same non-interactive form. Once accepted, start no further work and finish the current response normally. Acceptance is not yet proof that the whole Run succeeded. Do not use `chat session finish` as a substitute.

If a Session Step needs an unplanned human decision, create a Project Ask and register `chat wait --all --ask <ask-id> --project <team>/<project>`, then end the turn without completing the Step. On continuation, read `chat ask show <team>/<project> <ask-id>`, resolve the answer or cancellation, and finish the Step. A Workflow Attempt can wait on same-Project Asks, not on Session or Run targets.

## Human decisions and reusable children

A planned Decision Step creates a Project Ask for the human who started the Run, or the human owner of the agent that started it. There is no assignee field in the Decision definition. Answer it in the Project's Ask interface. The Run uses a pinned answer revision as `{"answer": "..."}`; a later edit to the Ask does not rewrite that output. `waiting_for_decision` is an intermediate state, not a failure. This is a business decision, distinct from a coding Runtime asking permission to use a tool. An answer supplies data to downstream Steps. Branching requires explicit `when` conditions as below; an answer does not grant deployment authority.

A Workflow Step can call a published Workflow in the same Project. Its child Revision is pinned, and only one level of composition is supported. See the complete [definition reference](/en/docs/workflow-reference) for Decision and child examples, typed bindings, and limits.

## Choose a branch and collect its result

Use this example only after confirming the compatible API/server, WebUI, and CLI described in the [version prerequisite and definition rules](/en/docs/workflow-reference). Availability in your environment is not established by this guide or by a successful syntax check. If validation rejects `when`/`join`, or the Run view lacks condition/skip details, stop and check the deployed version with your administrator.

This Workflow asks which note to prepare, runs one branch, and exports the join's summary. It does not publish or deploy anything. As with `greeting`, inspect Project members and Runtime profiles, then run `chat workflow init choose-note --project <team>/<project>` (choose another slug if occupied). Replace the Draft's `workflow.yaml` with the following. Replace all three `writer.yourname` entries and Runtime settings with the actual supported member/profile.

```yaml
schema_version: 1
name: choose-note
description: Choose a note, then summarize the branch result.
inputs:
  type: object
  additionalProperties: false
  properties: {}
outputs:
  summary: "{{ steps.summary.outputs.text }}"
steps:
  choose:
    needs: []
    decision:
      question: Which note should be prepared?
      body: { file: prompts/choose.md }
      options: [Draft, Hold]
  draft:
    needs: [choose]
    when:
      value: "{{ steps.choose.outputs.answer }}"
      equals: Draft
    session:
      agent: writer.yourname
      runtime: { kind: codex-acp, config: {} }
      prompt: { file: prompts/draft.md }
    outputs:
      type: object
      additionalProperties: false
      properties:
        text: { type: string, minLength: 1 }
      required: [text]
  interpret:
    needs: [choose]
    when:
      value: "{{ steps.choose.outputs.answer }}"
      otherwise: true
    session:
      agent: writer.yourname
      runtime: { kind: codex-acp, config: {} }
      prompt: { file: prompts/interpret.md }
    outputs:
      type: object
      additionalProperties: false
      properties:
        text: { type: string, minLength: 1 }
      required: [text]
  summary:
    needs: [draft, interpret]
    join: true
    session:
      agent: writer.yourname
      runtime: { kind: codex-acp, config: {} }
      prompt: { file: prompts/summary.md }
    outputs:
      type: object
      additionalProperties: false
      properties:
        text: { type: string, minLength: 1 }
      required: [text]
```

Create `prompts/choose.md` in the same Draft:

```text
Choose Draft for a short planning note, or Hold to record that work is on hold.
You may also describe your conditions in your own words.
```

Create `prompts/draft.md` in the same Draft:

```text
Return a short planning note in text. Do not publish or deploy anything.

{{ aachat.step_completion }}
```

Create `prompts/interpret.md` in the same Draft:

```text
The human answered: {{ steps.choose.outputs.answer }}
Return a note in text preserving the answer and any conditions. Do not infer
approval or carry out the requested work. If another decision is necessary,
use a Project Ask and wait before completing this Step.

{{ aachat.step_completion }}
```

Create `prompts/summary.md` in the same Draft:

```text
Read the attached Workflow dependency results. Return a concise summary in
text using the succeeded outputs and explaining which branch was skipped.
Preserve any human conditions; do not treat a skipped branch as completed work.
If all dependencies were skipped, report that no branch work was performed.

{{ aachat.step_completion }}
```

From the Draft's Project directory, validate, then optionally try the Draft with the empty input object:

```bash
chat workflow validate workflows/choose-note
chat workflow run --draft workflows/choose-note --stdin <<'JSON'
{}
JSON
```

Open the returned Run in the Project's Workflows and answer its Ask. Selecting exactly `Draft` runs `draft` and skips `interpret`; selecting `Hold` or supplying free text runs `interpret` and skips `draft`. `Draft, after review` is free text, not approval for the `Draft` branch. A later Ask edit does not change the accepted answer for this Run. If `interpret` needs another decision, follow the Ask/wait procedure above before completing it.

After the selected branch succeeds, `summary` reads its accepted output and the other branch's skip reason. Each running Session submits its own schema-valid completion using the generated instructions. The summary Attempt may, for example, submit `{"outcome":"succeeded","outputs":{"text":"Work is on hold; the draft branch was skipped."}}` only if that describes the actual result. `accepted: true` acknowledges that Step's completion, not the whole Run's success.

Use `chat workflow status <run-id> --project <team>/<project>` to verify the Run is succeeded and `outputs.summary` exists and contains the expected result. Missing outputs are not an empty successful deliverable. Inspect the active Step, completion acceptance, or `output_error` before passing anything onward. When a child is involved, inspect the parent too: child success alone does not prove the parent accepted its output. After the trial, publish and run the published version using the earlier procedure with `choose-note` and `{}`.

This Decision example always selects one of the two branches after an answer. With boolean/enum conditions, an uncovered value can skip every branch: a join still runs and must report that no branch work occurred. An ordinary downstream Step would skip instead. Do not count skipped work as performed or retry it to force a branch; correct the Draft or input and use a new Run if the intended choice was different.

## Read the Run and recover

In WebUI, open the Project's Workflows, select the Workflow, and open a Run. The dependency graph and Step details let you inspect inputs, outputs, Attempts, source Session, linked Ask, and child Run. Open the relevant Attempt or child before deciding how to recover. CLI `status` includes `available_actions`; these reflect current state and authority, and are rechecked when you act.

| Observed state or problem | Next action |
|---|---|
| Work is running or waiting for a decision | Inspect the active Step or answer the Ask; do not launch a duplicate to obtain a result. |
| `skipped` with `condition_not_matched` | Compare the recorded reference and actual value with the condition. No Attempt, Session, Ask, signal, or child Run was created for this Step; it has no retry action. |
| `skipped` with `dependency_skipped` | Inspect the named upstream Step's skip reason. Ordinary downstream work also skips; use an explicit join when it must collect the remaining results. |
| A join has not started or has failed | Check every dependency. Failed, cancelled, blocked, or unresolved work is not a successful skip. Repair the cause and retry only when offered; a failed join can be retried with skipped dependencies when listed in `available_actions.retry_steps`. |
| `attention_required` | Inspect the failed Step and cause. It is settled, not succeeded. |
| Retry is offered | Run `chat workflow retry <run-id> --step <step-key> --project <team>/<project>` only for a key in `available_actions.retry_steps`. |
| A Workflow Step failed in its child | Open the child Run and retry the failed inner Step when offered. |
| Cancellation is needed | Use `chat workflow cancel <run-id> --project <team>/<project>` only when `available_actions.cancel` is true. Cancel a child through its parent. |
| Definition or immutable input is wrong | Correct and validate the Draft, publish if needed, and start a new Run. Retrying does not adopt Draft edits. |
| Decision Ask was cancelled or its assignee is unavailable | Repair the cause and retry when offered; a retry creates a new Ask. An oversized rendered Decision has no retry action. |
| Runtime cannot start | Restore the execution owner's runtime/configuration, then follow the available retry action. Ordinary Session resume is not supported for Workflow Attempts. |

For several root Runs whose results must be combined, start them without individual `--wait` flags and register one explicit wait:

```bash
chat wait --all --workflow <first-run-id> --workflow <second-run-id> --project <team>/<project>
```

Child Runs belong to their parent and cannot be wait targets. When continued, inspect each result using the supplied `Read:` command. Settled results can include attention or cancellation; waiting is not an assertion of success.

To pass a successful result to another Workflow, inspect both schemas, then select only the keys accepted by the next closed input object. For a next Workflow named `save-greeting` that declares `greeting`:

```bash
chat workflow status <run-id> --project <team>/<project> | jq '.outputs | {greeting}' | chat workflow run save-greeting --project <team>/<project> --stdin
```

Run this only after confirming success and the presence of `outputs`; do not pipe a failed status into a new Run. Store large deliverables in [Shared Documents](/en/docs/shared-documents) or [Media](/en/docs/media) and return a bounded reference. Completion and Run outputs are limited to 128 KiB and JSON depth 32. `workflow_completion_limit_exceeded` requires smaller outputs and a corrected new Run; a historical succeeded Run can report `output_error` instead of oversized outputs.

## Improve the next Revision

When a prompt, input, output schema, or agent assignment caused a concrete problem, leave Attempt feedback. In the current Attempt use `chat workflow feedback --stdin`; outside it use the Run ID and Step, with optional `--attempt N`:

```bash
chat workflow feedback <run-id> --step write --project <team>/<project> --stdin <<'TEXT'
The prompt did not specify the reader's language. Add a language input before the next revision.
TEXT
```

Feedback is plain text, up to 8,192 bytes. Do not invent scores. Read it in Run status or the Run screen and use the improvement action to prepare Draft changes. Feedback alone changes no prompt. Edit the normal Draft, validate it, optionally try it, and publish the next Revision. Keep Run logs in Run history.

In WebUI, choose **Ask an agent to improve** to prepare and focus a new Session's launch draft. If another draft is already entered, review the replacement confirmation. Check the Project, Workflow slug, and normal Draft path in the prepared prompt, select the Agent and Runtime, then send to start the improvement Session. Preparing the draft is not Session-start acceptance. Open the started Session to follow its edits; an existing Run still uses its pinned Revision.

## Archive and restore

Use **Archive** in a Workflow's row or detail menu to remove it from the active list and stop new Runs. The confirmation shows active Triggers that will pause, Runs that will continue, and published parents that prevent archiving. Drafts, published Revisions, and all Run history are preserved. Existing Runs can finish, retry, or be cancelled.

Switch the list to **Archived** to restore the same Workflow. Restore archived child Workflows first when prompted. Restoring does not resume Triggers: open Triggers and explicitly resume each one after checking its inputs and schedule. There is no permanent-delete action.

Agents can use `chat workflow archive <slug> --project <team>/<project>` and `chat workflow restore <slug> --project <team>/<project>`. Add `--preview` to inspect the impact without changing anything; `chat workflow list --archived --project <team>/<project>` includes unpublished archived Drafts. An archived Draft remains visible at its original path but cannot be edited or published. After restoring, retrieve the latest files and resolve any preserved local edits before publishing.


---

# Workflow definition reference

> Bundle paths, Step kinds, typed schemas, prompt references, child Workflows, commands, and execution limits.

# Workflow definition reference

Use this reference while editing `workflow.yaml`. The [Workflow guide](/en/docs/workflows) provides a complete Session Step example and the create-to-result procedure. Definitions use YAML with `schema_version: 1`; unsupported fields are rejected. YAML anchors, aliases, merge keys, and tags are not supported. Validate the actual Draft before publishing or running it.

## Definition fields

| Field | Contract |
|---|---|
| `schema_version` | Required integer `1`. |
| `name` | Required non-empty display name; the Draft directory slug identifies the Workflow. |
| `description` | Required description string. |
| `inputs` | Required closed object schema for Run input. Use empty `properties: {}` for no inputs. |
| `steps` | Required map of 1–64 Steps. Keys match `^[a-z][a-z0-9_-]{0,63}$`. |
| `outputs` | Optional map from public output name to one complete Step output reference. This is a binding map, not a JSON Schema. Default: no exported values. |
| `steps.<key>.needs` | Required list of direct dependencies; `[]` for a root. Up to 32 per Step and 256 edges overall. Unknown or repeated dependencies and cycles are rejected. |
| `steps.<key>.when` | Optional condition on a direct dependency output; applies to any Step kind. Use `value` and exactly one of `equals` or `otherwise: true`. |
| `steps.<key>.join` | Optional boolean, default `false`. `true` requires a Session, non-empty `needs`, and no `when`. |
| `steps.<key>.session` | Exactly one Step kind. Requires `agent`, `runtime`, and `prompt.file`. A Session Step also declares an `outputs` schema. |
| `steps.<key>.decision` | Exactly one Step kind. Requires static non-empty `question` and `body.file`; optional `options`. Do not declare Step `outputs`. |
| `steps.<key>.workflow` | Exactly one Step kind. Requires published child `slug`; `inputs` binds child fields. Do not declare Step `outputs`. |

For a Session Step, `runtime.kind` is mandatory. `runtime.config` is a map of option IDs to strings or booleans and may be omitted or set to `{}`. Strings are ACP option value IDs, not arbitrary display labels; numeric values are not accepted. Discover available kinds and options with `chat project members <team>/<project> --runtime-profiles`. Agent membership, owner availability, and Runtime compatibility still matter at execution.

`needs` orders execution; it is not a conditional expression. A Session, Decision, and child Workflow cannot share one Step definition. Files in `scripts/` are supporting assets that an agent may use; their presence does not create a shell Step or run a command automatically.

## Conditions, skipped Steps, and joins

**Version prerequisite:** These fields require a compatible API/server, WebUI, and CLI. Availability in your environment has not been confirmed here. Before using them, confirm the deployed version with your administrator, validate the actual Draft against that server, and check a trial Run's conditions, skip reasons, and outputs. An unknown-field error or missing condition/skip display is a reason to stop and check versions, not to remove the condition and run unconditionally. See the [complete branching example](/en/docs/workflows).

`needs` still declares dependencies; add `when` explicitly to select work by result. `when.value` must be one complete `{{ steps.<direct-need>.outputs.<path> }}` reference to a required boolean or string enum. Decision `answer` is the only free-text string exception. `equals` preserves type and value: boolean `true` differs from string `"true"`; strings are not trimmed or interpreted. For enums, the comparison must be a declared value. Run inputs, optional paths, arbitrary expressions, coercion, loops, and error-recovery branches are not supported.

`otherwise: true` matches only when none of the `equals` comparisons on the **same normalized reference anywhere in the Revision** match. At least one such `equals` is required; at most one `otherwise` is allowed per reference. Multiple Steps with the same matching value all become eligible. A boolean or enum may have uncovered values with no branch work.

For Decision answers, `equals` must match a published option. Branching on an answer requires an `otherwise` **Session**, whose only `needs` entry is that Decision and whose prompt directly references its `answer`. It receives free text and uncovered options. Preserve the human's conditions and authority; ask for a further decision when needed. Matching an answer grants no new authority, and editing the Ask later does not change the pinned answer revision.

A condition mismatch derives `skipped`; an ordinary Step depending on a skipped Step also skips. No Attempt, Session, Ask, signal, or child Run is created for the skipped Step. Failure, cancellation, blocked work, and unresolved dependencies are not successful skips.

A `join: true` Session waits for **every** direct dependency to succeed or skip, and runs even when all of them skip. It does not bypass failure or cancellation. Its prompt must not directly reference `steps.*.outputs.*`. Instead, read the server's `Workflow dependency results` attachment immediately before the completion instructions: a canonical JSON array in Step-key order, with `step`, `state`, and either accepted `outputs` or skip `reason` for each dependency. It counts toward the 100,000-byte prompt limit and is preserved for retry and prompt history.

Top-level `outputs` cannot reference a potentially skipped Step, including ordinary downstream Steps that inherit skip. Export a required join output instead. All Steps being succeeded or skipped can finish a Run successfully, but Run outputs require accepted successful completions from every executed Step. A child Run's success alone does not establish that its parent Step has accepted its outputs. Check the parent Run and actual `outputs` before using the result.

## Bundle files and paths

The editable root is `aachat/projects/<team>/<project>/workflows/<slug>/`. A Bundle contains required `workflow.yaml`, optional root `README.md`, and text files under `prompts/` or `scripts/`. Session `prompt.file` and Decision `body.file` point to a file below `prompts/` that exists in the Bundle.

Use relative, case-sensitive paths and ordinary UTF-8 text. Absolute paths, backslashes, empty or dot path segments, dotfiles, `_published`, duplicate paths, and U+0000 are rejected. The Bundle is not a general repository snapshot; keep unrelated files outside it. The executing Attempt sees only its pinned read-only Bundle at `$AA_WORKFLOW_DIR`.

## Supported input and output schemas

The root of Run `inputs` and Session Step `outputs` must be an object. **Every object, including nested objects, must have `additionalProperties: false`.** Declare fields under `properties` and required fields under `required`. An optional property can be absent; do not use `null` as a substitute for an absent field.

| Supported construct | Values or keywords |
|---|---|
| Types | `object`, `string`, `number`, `integer`, `boolean`, `array` |
| Object | `properties`, `required`, `additionalProperties` |
| Array | `items`, `minItems`, `maxItems` |
| String | `minLength`, `maxLength`, `pattern`, `format` |
| Number | `minimum`, `maximum` |
| Shared | `type`, `enum`, `description` |

The only supported `format` is `uri`. Arbitrary JSON Schema is not accepted: no `$ref`, `allOf`, `oneOf`, `anyOf`, nullable types, or union type arrays. Use small inline schemas. A document path can be an ordinary string; `format: uri` is for a URI, not a promise that an artifact exists or that its access permissions are suitable.

## Prompt references and exported values

A Session prompt may contain text and `{{ inputs.reader }}` or `{{ steps.write.outputs.greeting }}`. A Step output reference must name a **direct** dependency declared in `needs`; depending on an intermediate Step does not expose all of its ancestors. Referenced schema paths must exist. The generated completion marker `{{ aachat.step_completion }}` must occur exactly once at the end of every Session prompt, with only whitespace after it.

Decision bodies can use the same input and direct dependency references but must not contain the completion marker. Questions and options are static. The Run creates the Ask and accepts the human answer; no agent submits a Decision completion payload.

Top-level `outputs` names map to Step output paths that are required by the source schema, such as `greeting: "{{ steps.write.outputs.greeting }}"`. A top-level output cannot reference Run input directly. The server derives a closed output schema from the bindings. Successful child output is written once to its parent Step before downstream work starts.

## Complete child and Decision example

First publish `greeting` from the [guide](/en/docs/workflows) in this same Project. Then create the `approve-greeting` Draft with `chat workflow init approve-greeting --project <team>/<project>` and write this `workflow.yaml`:

```yaml
schema_version: 1
name: approve-greeting
description: Ask a human to review a generated greeting.
inputs:
  type: object
  additionalProperties: false
  properties:
    reader:
      type: string
      minLength: 1
  required: [reader]
outputs:
  greeting: "{{ steps.compose.outputs.greeting }}"
  answer: "{{ steps.review.outputs.answer }}"
steps:
  compose:
    needs: []
    workflow:
      slug: greeting
      inputs:
        reader: "{{ inputs.reader }}"
  review:
    needs: [compose]
    decision:
      question: Is this greeting ready to use?
      body:
        file: prompts/review.md
      options: [Use it, Revise it]
```

Create `prompts/review.md`:

```text
Please review this greeting for {{ inputs.reader }}:

{{ steps.compose.outputs.greeting }}

Choose whether it is ready, or explain the revision needed.
```

Validate, optionally run the Draft with `{"reader":"Alex"}`, and publish using the guide's procedure with `approve-greeting` as the slug. The child produces `greeting`, and then the human Run starter (or the starting agent's human owner) receives the Ask. There is no configurable Decision assignee. A successful Run exports both `greeting` and `answer`. Selecting `Revise it` still completes the Decision with that answer; this definition has no subsequent revision Step. Add an explicit downstream Session Step to interpret the answer, or use `when` with the required `otherwise` Session to select branches.

Decision `options` must be omitted/empty for free text, or contain 2–5 distinct values. Do not add `outputs` to the Decision: its derived schema is an object with required string `answer`. The server fixes the accepted answer revision; editing the Ask afterward cannot change this Run.

A child `workflow.inputs` entry is either a literal JSON value or a single complete input/direct-dependency reference. Do not interpolate text around a reference. Bind every required child input, and provide only fields accepted by its schema. Every referenced source path must be required, even for an optional destination input. Its schema must be a subset of the destination contract, including supported constraints; matching only the primitive type is insufficient. For example, `reader: Alex` is a literal alternative to `reader: "{{ inputs.reader }}"`.

The server pins the child's current published Revision during validation for run/publication. The child must be available in the **same Project**, and that pinned child may contain only Session and Decision Steps. Nested child Workflows are rejected. Publishing a newer child later does not change an existing parent Revision or Run. Revalidate and publish the parent Draft to adopt it. Open a failed child Run to repair its inner Step; cancel a child through the parent Run.

## Command reference

These are Session-agent commands. Substitute real identifiers. Most Project commands accept `--project <team>/<project>` or infer the Project from cwd. `validate` requires the Draft's Project cwd and server access. `publish` and `run --draft` derive the Project from the Draft path. `complete` targets the current Attempt and takes no Run ID.

| Operation | Invocation |
|---|---|
| Create Draft | `chat workflow init <slug> --project <team>/<project>` |
| Validate | From the Draft Project: `chat workflow validate workflows/<slug>` |
| Published list | `chat workflow list --project <team>/<project> [--last 50] [--before <cursor>]` |
| Published contract and Step list ([pre-run checks](/en/docs/workflows)) | `chat workflow show <slug> --project <team>/<project>` |
| History | `chat workflow runs [<slug>] --project <team>/<project> [--last 50] [--before <cursor>]` |
| Draft Run | `chat workflow run --draft <draft-path> --stdin` |
| Published Run | `chat workflow run <slug> --project <team>/<project> --stdin [--wait]` |
| Publish | `chat workflow publish <draft-path>` |
| Run detail | `chat workflow status <run-id> --project <team>/<project>` |
| Cancel | `chat workflow cancel <run-id> --project <team>/<project>` |
| Retry | `chat workflow retry <run-id> --step <key> --project <team>/<project>` |
| Complete Attempt | `chat workflow complete --stdin` |
| Attempt feedback | `chat workflow feedback [<run-id> --step <key> --project <team>/<project>] [--attempt N] --stdin` |

Square brackets above mean optional arguments; do not type them. `run` takes exactly one of `--stdin` and `--input-file <path>`. `list` and `runs` page sizes are 1–100, default 50. Project-wide `runs` shows roots; passing a Workflow slug includes its root and child Runs, with parent identity. `init`, `run`, and `retry` accept `--client-nonce <uuid>` for retrying the exact same request; do not reuse a nonce for changed input. Always obey `available_actions` and structured recovery responses. `--wait` registers durable waiting and does not block the CLI.

## Limits and how to recover

| Surface | Limit | If exceeded |
|---|---|---|
| One Bundle file | 256 KiB | Shorten or split supporting text. |
| Whole Bundle | 1 MiB, 128 files | Remove unrelated assets. |
| Relative path | 256 UTF-8 bytes | Shorten paths. |
| Dependency graph | 64 Steps, 32 needs per Step, 256 edges | Reduce the graph within the one-level composition rule. |
| Rendered Session prompt | 100,000 bytes including generated completion instructions | Shorten prompt/input/upstream text. |
| Decision question / each option | Non-empty; 2,000 / 200 bytes | Shorten the static text; keep 2–5 distinct options or use free text. |
| Rendered Decision body | 100,000 bytes | Correct the immutable input or definition in a new Run. |
| Run input | 128 KiB, JSON depth 32 | Store large content in a Project resource and pass a reference; flatten deeply nested input. |
| Completion JSON / Run outputs | 128 KiB, JSON depth 32 | Return short artifact references. |
| Failed completion diagnostic | Non-empty, at most 4 KiB | Keep the cause and next action, shorten the diagnostic, and retry. |
| Attempt feedback | 8,192 bytes | Keep a concrete note about the problem. |

KiB and MiB are binary units; the byte limits are not character counts. These are Workflow limits, separate from Database SQL or Session follow-up scheduling limits. A successful schema check cannot establish that a Runtime can execute or that a generated deliverable is correct. Use the [Run recovery guide](/en/docs/workflows) for state-based retry, cancellation, and completion acceptance, and the [Trigger guide](/en/docs/triggers) for scheduled dispatch failures.


---

# Triggers — schedule future work

> Start a Workflow or fresh Session on a schedule or document condition, inspect occurrences, and recover safely from conflicts or unknown outcomes.

# Triggers — schedule future work

A Project Trigger starts a **published Workflow or a fresh Session** when a time or document condition is met. Use it for repeated reviews, a one-time future task, or work that begins when a Shared Document reaches an agreed state. It never adds a turn to an existing Session. Existing-Session follow-up is a separate [Session](/en/docs/sessions) feature; immediate reusable work uses [Workflow run](/en/docs/workflows).

## Access and target preparation

Use an active Project. Viewers can inspect content; creating and managing automation needs collaborator/admin authority. For an agent-created Trigger, the agent's current human owner must also be an active Project collaborator/admin. For a Session target, choose an active collaborator/admin agent. The execution owner's runtime and selected agent configuration must be available when work starts. Scheduling does not grant repository, tool, or production permissions.

In WebUI, open the Project's **Triggers** and choose **New trigger**, or use **When** while preparing a supported fresh Session/Workflow request. Choose the target, schedule, timezone, and input, check the preview, and save. The Triggers list and detail show the next occurrence, history, and permitted management actions. Open the started Session or Run to inspect the work itself.

The following CLI operations are for an agent in a running aachat Session with Project access. **Every `chat trigger` command requires `--project <team>/<project>`**; cwd does not select it. Check the returned `project` before using a result. Replace placeholders with actual names and IDs.

```bash
chat trigger list --project <team>/<project>
chat workflow list --project <team>/<project>
chat workflow show greeting --project <team>/<project>
chat project members <team>/<project> --runtime-profiles
```

Pass each `next` from `list` to `--cursor` until `next` is absent before deciding that matching automation does not exist. Use the exact published Workflow slug or exact active agent name. The CLI resolves them; do not substitute their internal UUIDs.

## Create a weekday Workflow Trigger

First create and publish `greeting` using the [Workflow guide](/en/docs/workflows), or select another existing Workflow and adjust its input to the schema returned by `show`. Save this complete input as `trigger.json` outside the Workflow Bundle. Update the dates to a future range before using the example:

```json
{
  "name": "Weekday greeting",
  "description": "Generate a greeting on weekday mornings.",
  "schedule": {
    "kind": "calendar",
    "time": "09:00:00",
    "days": ["mon", "tue", "wed", "thu", "fri"],
    "timezone": "Asia/Singapore",
    "starts_on": "2026-09-07",
    "ends_on": "2026-12-31"
  },
  "target": {
    "kind": "workflow",
    "workflow": "greeting",
    "input": {"reader": "Alex"}
  }
}
```

Preview just the schedule, then create once:

```bash
jq '{schedule}' trigger.json | chat trigger preview --project <team>/<project> --stdin
chat trigger create --project <team>/<project> --stdin < trigger.json
chat trigger show <trigger-id> --project <team>/<project>
```

`preview` returns the server's canonical schedule and next three time occurrences without creating automation. Check local time, timezone, and dates. `create` creates a live Trigger, so its conditions can begin dispatching work. Record its ID, inspect `show`, and check occurrence history after it fires. An accepted occurrence means a target was started, not that its work succeeded.

The name must be 1–120 characters after trimming; an optional description is limited to 1,000 characters. Workflow `input` is checked against the current published input schema at creation/edit and again at dispatch. Publishing an incompatible input contract can automatically pause existing Triggers. A Trigger targets the published Workflow; unlike a parent Workflow Revision's pinned child, it does not freeze the published pointer at creation.

## Start a fresh Session instead

Replace the complete input's `target` with a Session target. Replace the illustrative member with a real Project member. `workspace_repo`, when present, must be the Project repository or Team default repository; otherwise omit it to use the effective configured repository:

```json
{
  "kind": "session",
  "agent": "reviewer.yourname",
  "prompt": "Review the Project's latest results and record the next decision.",
  "launch": {
    "runtime_kind": "codex-acp",
    "config_overrides": []
  },
  "workspace_repo": "owner/repository",
  "working_branch": "main"
}
```

`prompt` is the non-empty work request and is limited to 100,000 bytes. `launch`, `workspace_repo`, and `working_branch` are optional. With no `launch`, the server resolves the agent default. Use only Runtime kinds and typed config options advertised by `chat project members <team>/<project> --runtime-profiles`. For an advertised ID option, an override has the shape `{"id":"mode","value":{"type":"id","value":"agent-full-access"}}`; do not copy an option unless that agent exposes it. An empty override list selects no custom options. `working_branch` requires a configured Project or Team repository. Update the Project/Team repository settings before selecting a different repository; omit `workspace_repo` when the effective configured repository is suitable. Omit `working_branch` when neither repository exists. A named working branch is a repository selection, not permission to push directly to it.

## Schedule reference

These are individual `schedule` objects, not complete create requests. UTC timestamps end in `Z`; use a valid IANA timezone. Replace the example dates before they expire.

```json
{"kind":"once","at":"2026-09-07T01:00:00Z","timezone":"Asia/Singapore"}
```

```json
{"kind":"calendar","time":"09:00:00","days":["mon"],"timezone":"Asia/Singapore","starts_on":"2026-09-07","ends_on":"2026-12-31"}
```

```json
{"kind":"interval","every_seconds":3600,"starts_at":"2026-09-07T01:00:00Z","ends_at":"2026-09-30T01:00:00Z","timezone":"Asia/Singapore"}
```

| Kind | Meaning and constraints |
|---|---|
| `once` | One future UTC `at`; timezone supplies the local context. |
| `calendar` | Local `HH:MM:SS`, one or more distinct weekdays `mon`–`sun`, and local `starts_on`. Optional `ends_on` is inclusive. |
| `interval` | A UTC cadence of at least 300 seconds (5 minutes). `starts_at` is optional and defaults to acceptance time; `ends_at` is required and inclusive. |
| `document_match` | A same-Project frontmatter condition; no time preview and no Run now. |

Calendar schedules follow the timezone's daylight-saving rules. An ambiguous repeated local time fires once at the earlier instant; a nonexistent local time advances one second at a time, for up to four hours, to the first valid time. Always inspect the server preview around timezone transitions. An interval is elapsed seconds, not “the same local clock time every day.” These limits are different from existing-Session follow-up limits.

## Start when a document matches

Use this `schedule` in a complete create input with a prepared target:

```json
{"kind":"document_match","on":"reviews/release","match":{"status":"approved","ready":true}}
```

It watches `docs/reviews/release.md` in this Project. A matching [Shared Document](/en/docs/shared-documents) could have this frontmatter:

```yaml
---
title: Release review
status: approved
ready: true
---
```

`on` is the exact `kind/doc_id`, not a file path or a document in another Project. `match` must contain at least one field. Values are exact strings, numbers, or booleans; multiple fields are ANDed. `true` is a boolean, while `"true"` is a different string. Arrays, objects, and null are not match values.

A document condition can match immediately when created or revalidated. It dispatches at most once, rather than on every subsequent save. Saving the watched document evaluates the condition; `run` is not supported for document conditions. To arm it again after completion, submit a complete edit with a new document condition.

## Manage an existing Trigger

Read `show` before changing a Trigger. Its `state_version` can advance on either mutation or dispatch. Never hard-code a version or reuse an old one. `show` also returns `edit_input`, a complete reusable object containing the current version. When it is non-null, save it, change the desired fields while retaining the observed version, then submit the full replacement:

```bash
chat trigger show <trigger-id> --project <team>/<project> > trigger-state.json
jq '.edit_input' trigger-state.json > trigger-edit.json
```

```bash
chat trigger edit <trigger-id> --project <team>/<project> --stdin < trigger-edit.json
```

Make the intended changes to `trigger-edit.json` between those commands. `edit` is replacement, not a partial patch. Preview a changed time schedule before submission. If the target is unavailable, `edit_input` is null: select a new target and construct the complete name, schedule, target, optional description, and latest `state_version` yourself. An older server during a CLI/server version transition can also leave the target unavailable without reusable edit input; do not substitute a UUID. In returned Session edit input, preserve `working_branch: ""` when keeping the accepted repository default, or the non-empty value for the accepted named branch.

| Operation | CLI | Expected effect |
|---|---|---|
| Inspect page | `chat trigger list --project <team>/<project> [--cursor <cursor>] [--limit 50]` | States, next times, last outcomes; pass `next` to `--cursor`. |
| Inspect one | `chat trigger show <trigger-id> --project <team>/<project> [--cursor <cursor>] [--limit 50]` | State/version, actions, recent occurrences; pass `next` to `--cursor` for older history. |
| Preview | `chat trigger preview --project <team>/<project> --stdin` | Read-only schedule preview from `{"schedule": ...}`. |
| Create | `chat trigger create --project <team>/<project> --stdin` | A new live Trigger. |
| Replace | `chat trigger edit <trigger-id> --project <team>/<project> --stdin` | Full replacement with `state_version` in JSON. |
| Run now | `chat trigger run <trigger-id> --state-version <version> --project <team>/<project>` | One ordinary occurrence for the observed active time Trigger; schedule unchanged. |
| Pause | `chat trigger pause <trigger-id> --state-version <version> --project <team>/<project>` | Stop future dispatches. |
| Resume | `chat trigger resume <trigger-id> --state-version <version> --project <team>/<project>` | Resume a manually paused Trigger when offered. |
| Delete | `chat trigger delete <trigger-id> --state-version <version> --project <team>/<project>` | Remove future dispatches and preserve history. |

Square brackets mean optional arguments. List/history limits accept 1–100. Pause and delete never cancel or delete an already-started Session or Workflow Run. Manage that target separately when needed and authorized.

## Read outcomes and avoid duplicate work

A Trigger is `active`, `paused`, or `completed`. An occurrence is `accepted`, `skipped`, or `failed`. For `accepted`, follow its `workflow_run_id` or `session_id` and current target state. `run` returns the occurrence synchronously, but does not wait for the target's result. It advances `state_version` without changing `next_scheduled_for` or the recurring schedule.

| Occurrence or condition | What happens / what to do |
|---|---|
| Previous accepted target still active | The occurrence is skipped with `previous_run_active`; it is not queued. Inspect the previous target. |
| Previous Workflow Run is in `attention_required` | The next occurrence supersedes and cancels it, then starts new work with `previous_run_superseded`. Retry a stalled Run before that next occurrence if it must continue. Do not manually cancel it merely to unblock the Trigger. |
| Scheduler returns after downtime | Older due occurrences are skipped as `superseded_during_downtime`; only the newest due occurrence can start. |
| Dispatch fails | The Trigger pauses; inspect `occurrence.reason` and `pause_message`, repair the cause, and revalidate with a complete edit. |

A paused/completed Trigger or a document condition cannot be run now. A changed revision or dispatch already in progress conflicts before another target is started. Follow the returned action rather than forcing the request.

## Recover a conflict, pause, or unknown result

For a version conflict, run the exact Project-scoped `show` command returned by the error and decide again using the refreshed state. Do not merely replace the version in an old request without checking what changed.

**Create is non-idempotent.** If its structured error says the outcome is unknown, do not send the create JSON again. Follow the returned read-only `list` command through all pages and reconcile whether the Trigger already exists. If `run` has an unknown outcome, do not retry it; use the returned `show` command and occurrence history to find whether work started. If evidence still cannot establish the outcome, keep it unresolved rather than creating duplicate work. This differs from [Workflow completion](/en/docs/workflows), which permits retrying the exact same completion payload after transport uncertainty.

Manual pauses and automatic pauses have different recovery paths:

| State / reason | Recovery |
|---|---|
| Manually paused document condition | Resume directly when offered. |
| Manually paused time schedule | `show` checks for a future occurrence and offers resume only if one exists. Otherwise provide a complete future replacement. An edit preserves a manual pause: read the latest version with `show`, then use the offered `resume`. If that read fails, `show` fails instead of guessing. |
| `input_contract_invalid` | Match the current published Workflow input schema, then submit a complete edit. |
| `target_unavailable` | Restore or select an available Workflow/agent, then submit a complete edit. |
| `permission_revoked` | Restore the required authority and revalidate with an edit. If the creator is no longer owned by its execution owner, the old Trigger cannot be repaired: create a new one under the current owner. |
| `project_inactive` | Restore the Project to a state that permits work, then revalidate with an edit. |
| `completed` | Reactivate only by editing to a future time schedule or a new document condition. |

The server rechecks Project, creator, execution-owner relation, target, and Runtime authority at mutation and dispatch. A valid preview or an earlier successful occurrence is not a guarantee that later work will run. Read the started target's results and use the [Workflow recovery procedure](/en/docs/workflows) or [Session guide](/en/docs/sessions) for the execution itself.


---

# Project Database — store and query structured results

> Create a schema, store and read rows, browse tables, and recover from limits, migration conflicts, or an unknown write result.

# Project Database — store and query structured results

Use Project Database for structured results that agents and people need to reuse: customer records, research observations, or inventories. Use [Shared Documents](/en/docs/shared-documents) for the explanation and decisions around those rows. Each ordinary Project has its own server-managed Cloudflare D1 database, created lazily by its first migration. Reading the schema does not create a database. This is not a local SQLite file or an automatic backend for [HTML](/en/docs/html).

## Prerequisites and permissions

Ask an agent in a running Session that covers the active Project to operate the database. The Session's Project role controls access: Viewer can read schema and SELECT; Collaborator and Admin can also apply migrations and INSERT, UPDATE, or DELETE. Archived, completed, and deleting Projects do not accept new database operations.

`chat db` is a Session command. There are no Team, Project, Database ID, or Session selector flags: `schema` and `query` resolve the Project from the current directory, while `migrate` resolves it from the canonical migration file path. Run the examples from the Project root. The outer `aachat project database` command provides the catalog, not arbitrary SQL execution. Agents do not need direct D1 credentials.

## Create a table and save a result

Replace `acme/customer-research` with an existing Project covered by the Session. Start by reading its current schema:
```sh
cd aachat/projects/acme/customer-research
chat db schema
```

The read-only `db/schema.sql` projection starts with `-- aachat-schema-version: root` for an empty database, or a `sha256:...` version after migration. Do not edit that file. For this example, confirm the database is empty and create `db/migrations/add_customer.sql` with the following exact content. If it already has a schema, copy its **exact current version** into the parent header and adapt the SQL to existing tables; do not reuse `root`.
```sql
-- aachat-parent: root
CREATE TABLE customer (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  status TEXT NOT NULL
);
CREATE INDEX customer_status ON customer(status);
```

The parent header must start at byte 0. Save UTF-8 without a BOM or NUL, using a regular file rather than a symlink. Migration IDs use lowercase letters, digits, `_`, or `-`, start with a letter or digit, and have at most 128 characters. File sync saves the migration source; it does **not** apply SQL. Apply it explicitly, then insert and inspect one row:
```sh
chat db migrate db/migrations/add_customer.sql
chat db schema
chat db query --sql 'INSERT INTO customer (id, name, status) VALUES (?, ?, ?)' --params '["c1", "Ada", "active"]'
chat db query --sql 'SELECT id, name, status FROM customer WHERE status = ? ORDER BY id LIMIT 100' --params '["active"]'
chat db query --sql 'UPDATE customer SET status = ? WHERE id = ?' --params '["reviewed", "c1"]'
chat db query --sql 'SELECT id, name, status FROM customer WHERE id = ?' --params '["c1"]'
```

After a successful migration, the schema has a new version and the table and index appear. The first SELECT returns `c1`, `Ada`, `active`; after the UPDATE, the final SELECT returns `c1`, `Ada`, `reviewed`. Read the actual JSON response at each step before continuing. Repeating the INSERT with the same primary key is not a fresh record. For a deliberately disposable example row, remove it with `chat db query --sql 'DELETE FROM customer WHERE id = ?' --params '["c1"]'`, then SELECT by that key to confirm absence.

## Query and migration have different SQL rules

Both accept at most **100 KiB** of SQL. Neither permits reserved `_aachat_`, `sqlite_`, `_cf_`, or `pragma_` relations, qualified database object names, or arbitrary SQLite extensions.

| Operation | Allowed input | Important limits |
|---|---|---|
| `chat db query` | Exactly one SELECT, INSERT, UPDATE, or DELETE; no RETURNING or OUTPUT | Positional `?` only; `--params` is a JSON array of strings, at most 100, with exactly one value per placeholder |
| `chat db migrate` | 1–100 statements from the migration allowlist below | No parameter bindings; current parent version required |

Query cannot run DDL or PRAGMA. SELECT returns at most **1,000 rows and 1 MiB of decoded result data**; an oversized result is an error, not a partial page. Choose explicit columns, a WHERE clause, and a small LIMIT. A supplied LIMIT must be a static nonnegative integer, not a placeholder or expression. UPDATE and DELETE cannot use ORDER BY or LIMIT in this query interface.

The migration allowlist is ordinary CREATE TABLE and CREATE INDEX; ALTER TABLE to add, drop, or rename a column or rename a table; DROP TABLE or DROP INDEX for a single object; INSERT, UPDATE, and DELETE without RETURNING or OUTPUT; and **`PRAGMA defer_foreign_keys = ON`**. This PRAGMA is a migration-only exception. SELECT, arbitrary PRAGMA, views, triggers, and explicit transaction-control scripts are not migration operations. The allowlist does not make every SQLite dialect feature valid.

## Browse results in the WebUI

Open the Project's **Database** tab, select a table, and inspect its columns and rows. The browser is read-only: it has no SQL editor or mutation controls. Click a column heading to cycle sorting, and use pages of 25, 50, or 100 rows (default 100). Table, page, page size, and sort are retained in the URL.

A data change displays **Updates available**; refresh to load new rows. Schema changes refresh the catalog. Empty strings, NULL, and BLOB values are distinct. If a page exceeds 1 MiB, try 25 rows; if that still fails, ask the agent to SELECT fewer columns or smaller values.

## Recover without duplicating a write

Read the response's `error`, `reason`, and next action. A timeout does not prove that a write failed.

| Symptom | Next step |
|---|---|
| Project cannot be resolved or access is denied | Check Project-root cwd, Session coverage, active status, and the agent's role. Moving a file does not grant permission. |
| Migration source is rejected or missing | Read `db/_errors.md`; fix the path, header, encoding, or SQL, and allow sync to accept the file before applying. |
| Parent version is stale | Read current schema and prepare a revised migration against that version. Only one child can advance a parent; there is no force option. Keep accepted migration sources unchanged. |
| Migration is reconciling | Follow the returned read/recovery action. The server reconciles its operation and provider ledger; schema reads and the next migration wait until it resolves. SELECT/DML may continue under normal admission rules. |
| `OPERATION_OUTCOME_UNKNOWN` after DML | Read the known primary key and current values before deciding whether another write is needed. Never blindly repeat INSERT, UPDATE, or DELETE. |
| Query is busy | Another live query holds the Project lease. Follow the retry guidance; do not submit concurrent writes to work around it. |
| Result too large | Narrow columns/rows and use bounded pages rather than assuming truncated data is complete. |

Deleting a local migration or schema file does not undo applied data. Project deletion waits for accepted queries and unresolved migrations, and for physical database deletion. It is not an instant rollback or backup mechanism. See [Trust Boundary](/en/docs/trust-boundary) and [Projects](/en/docs/projects).

## Empty states and full cell values

In the WebUI Database browser, **No database yet** means the first migration has not initialized the database: ask an Agent to create and apply it using the steps above. **No tables yet** means there are no user tables; create a table through a migration and refresh the browser. Reading the schema alone does not initialize a database.

Click a non-NULL cell to open its full value and use **Copy** if needed. Empty string is distinguishable from NULL and can open the detail; a NULL cell has no detail button. This is a read-only inspection surface, not an editor. After an Agent changes rows or schema, use Refresh/Updates available to load the current state.


---

# Sharing — choose the audience and revoke access

> Compare member access, public document and AI context links, HTML shares, and media references; understand live reads, expiry, and revocation.

# Sharing — choose the audience and revoke access

Choose what a recipient should be able to read before copying a link. A normal Project URL requires membership. A public share URL grants read access to anyone who possesses it, including an external AI service you paste it into. It does not grant membership or permission to edit or run agents.

## Choose a sharing method

| Need | Method and audience | Who manages it / lifetime |
|---|---|---|
| Work together inside the Project | Normal Project/document links; authenticated members and their roles | Manage membership in [Projects](/en/docs/projects); a copied URL does not add a member |
| Let an outsider read one deliverable | Public document Markdown link, including supported media referenced by that document | Collaborator/Admin create; creator manages their own document links, Admin all links; UI expiry 7 days |
| Give an external reader broad Project context | Public AI context Markdown link, Project timeline, documents, and Project session transcripts | Admin only; UI expiry 7 days |
| Show an interactive static report | [Share HTML](/en/docs/html), Project HTML snapshot and its media dependencies | Human Collaborator/Admin; default 7 days, maximum 30, optional password, reset or stop |
| Reference an image, video, or PDF internally | [Media canonical URL](/en/docs/media), `/m/<uuid>` | Authenticated membership in the owning active Project; it is not a public sharing token |
| Invite someone to participate | Project join link | Membership/invitation rules apply; see [Projects](/en/docs/projects), not the public read-only share rules |
| Reuse a Project structure or a client entry | Template or connected-repository entry | A separate reuse/start-work flow; see [Connected repo](/en/docs/connected-repo) |

Publishing a Media asset to a Project does not by itself publish it anonymously. A Markdown or HTML share can expose its authorized media dependencies through that share's delivery path. Review images, PDFs, and video as well as text before sharing.

## Share one document

1. In an active ordinary Project where you are Collaborator or Admin, open the saved document in **Docs**. Check the entire current body, frontmatter, and referenced media.
2. Select **Create public document link** (the globe button). Confirm **Create and copy public link**.
3. Paste the copied URL into the intended reader or external AI tool. The URL has the form shown below; use the returned URL as-is rather than constructing it.
4. Open the link in a signed-out browser to check the recipient's view. It returns read-only Markdown, not the full document editor. WikiLinks and structured blocks do not grant access to other documents or execute work.

```text
https://aachat.io/share/<token>/docs/<kind>/<id>.md
```

A document share is bound to that document, not to every document linked from it. It cannot read Project context or session transcripts. Supported references to ready Project Media in its current content can be delivered through the share. Removing a current media reference removes that dependency's authorization through this share.

## Share Project context with an external AI

An Admin can use **Create public AI context link** in the Project header, review the warning, and select **Create and copy public link**. The returned URL ends in `/context.md`. Read it and follow its document, session, and pagination links before deciding that its scope is appropriate.

**This is broad Project read access, not a hand-picked set of documents.** The context surface contains Project timeline records and a document catalog, and the token permits reading documents and session transcripts in that Project. Older records are available through pagination. Do not assume that only links visible on the first page define the token's authority. Referenced ready media may also be exposed. A single-document share is the narrower choice for a finished report.

Both Markdown share types perform a **live read**. Later edits are visible through an existing token, and a context token can reach later Project records. The link is not a frozen export of what you reviewed at creation. Keep future confidential work outside a shared scope, or revoke the link before adding it.

## Expiry, listing, and revocation

The WebUI creates Markdown shares for **7 days** and has no expiry picker. The create API accepts `expires_in_days` from **1 to 30**, default 7; this does not imply an expiry editor or renewal button in the UI. Markdown shares do not have the HTML share's password/reset/extend controls.

Open **Project Settings → Public shares** to inspect active links by scope and expiry. Collaborators can see and revoke only document shares they created. Admins can see and revoke all active document and context shares. Viewers cannot create or manage them. Select **Revoke**, then confirm; the URL stops authorizing subsequent reads.

Existing URLs cannot be copied again from the list because raw tokens are not stored. If the URL is lost or clipboard copying fails after creation, inspect the active list, revoke the unwanted link, and create a new one. Repeated creation produces separate links; it does not replace the old token.

A revoked or expired token, or a Project that is no longer active, cannot be used to read the share. Revocation cannot retrieve a recipient's downloaded copy or remove content already sent to another service.

## If sharing fails

- A missing or disabled action: check that you are in an active ordinary Project and have the required role. Use a document share as Collaborator; context creation requires Admin.
- A reader sees not found: check expiry and revocation in Public shares, Project status, whether the document still exists, and whether the URL is exact. A document token cannot be repurposed for context, another document, or a session URL.
- A media reference fails: check that the current shared content still references a ready asset. Do not paste a short-lived signed storage URL as a workaround.
- The audience needs to edit or operate agents: use Project membership. Public read-only shares cannot provide those permissions.

For where data is stored and where HTML JavaScript executes, see [Trust boundary](/en/docs/trust-boundary).


---

# Meetings — Team meeting records

> Save decisions and evidence in Markdown for humans and agents. Learn WebUI and CLI creation, permissions, snapshots, and recovery after network failures.

# Meetings — Team meeting records

A Team Meeting is a shared record of the meeting time, participant labels, discussion, decisions, and follow-ups in Markdown. It does not host meetings, calls, recording, or transcription. Save prepared notes so humans can revisit Team history and agents starting later Sessions can consult recent discussions.

This is separate from a Shared Document with a `meeting` kind inside a Project. Use [Shared Documents](/en/docs/shared-documents) for Project work products and [Concept Registry](/en/docs/concept-registry) for reusable team decision criteria. Saving a Meeting does not automatically publish a Concept or start a Project.

## Save and revisit notes in the WebUI

Sign in and confirm membership in the intended Team. This is a Team-shared record; the participant field does not restrict access to the people listed.

1. Open Meetings in the Team sidebar, then choose Add meeting from the list.
2. Enter the Title and the start time in Date and time. The time input uses the browser's local time. Account for the offset when recording a meeting held in another timezone.
3. Enter one name per line in Participants. These are optional display labels; the field can be empty. It neither grants Team membership nor sends invitations.
4. Paste Markdown into Notes and select Save meeting.
5. On the resulting detail page, verify the title, time, participants, and body. The Meetings list sorts newest start times first; use Load older to reach older records.

For example, separate decisions and next actions in Notes.

```markdown
# Decisions

Keep the help center focused on frequently asked questions.

# Evidence

Three support conversations raised the same setup question.

# Follow-ups

Ada will draft a setup article and ask the team to review it.
```

To correct a record, choose Edit on its detail page, then Save meeting and verify the text. If someone updates the record while you are editing, a notification preserves your draft. Copy any changes you need before choosing Reload latest. This is not an automatic merge or a guarantee that concurrent edits will be preserved.

Delete on the detail page opens a confirmation dialog. Only a human Team Owner/Admin can delete. Preserve any needed record before deleting it.

## Save completed notes with the CLI

Prepare the body above as a UTF-8 file named `notes.md`. For the outside human CLI, replace `acme` with a Team slug where you are a member. Specify the timestamp in RFC3339 with an explicit timezone.

```sh
aachat meeting create acme \
  --title 'Help center review' \
  --started-at '2026-09-06T09:00:00+08:00' \
  --participant 'Ada' \
  --participant 'Grace' \
  --stdin < notes.md
```

A Session agent creates a record in its Session's Team with this command. Do not add a Team or Project positional argument.

```sh
chat meeting create \
  --title 'Help center review' \
  --started-at '2026-09-06T09:00:00+08:00' \
  --participant 'Ada' \
  --participant 'Grace' \
  --stdin < notes.md
```

Repeat `--participant` or omit it entirely. Check the successful result's Meeting ID and saved content, then open that record in the Team's Meetings UI. The agent command creates new records only; it cannot update or delete an existing Meeting. Ask a human to make corrections. Neither CLI provides Meeting list/show/edit commands; use the WebUI for full history and editing.

## Permissions and input limits

| Operation or input | Requirement |
|---|---|
| Human read, create, update | Active Team membership. Members can correct other people's records too |
| Human delete | Team Owner/Admin only |
| Session agent create | A Session accepting commands, with collaborator/admin membership in an active Project or DM in the same Team, and that Project in Session coverage |
| Title | 1–120 characters after trimming |
| Participants | 0–50 labels, each 1–120 characters after trimming |
| Notes | Must not be whitespace-only; at most 100,000 UTF-8 bytes |

The body limit counts bytes, not characters. Japanese text and emoji can use multiple bytes per character. If notes exceed the limit, edit them down and keep detailed supporting material in an appropriate Project document.

## Session context and current history

The database is authoritative. At Session start, up to 50 recent Meetings are projected as `aachat/meetings/<meeting-id>.md`, ordered by start time descending and then ID descending for equal timestamps. Each file includes `format: aachat.meeting/v1`, ID, title, start time, and participants in frontmatter, followed by the body.

This directory is a snapshot taken at startup and does not live-sync during the Session. Do not assume even a Meeting you just created has been added to the existing Session's snapshot. Check new records and corrections in the WebUI; a later Session receives a new snapshot. An older record missing from the 50 files has not necessarily been deleted. Browse full history in the WebUI.

These files are read-only. Editing, adding, or deleting them does not change server Meetings. Do not commit them to the workspace repository. Use the create commands above to save notes and the WebUI to correct them. A connected repo's Team projection has a separate update path; do not confuse it with a Session's 50-record snapshot.

## Recover from failures

| Situation | Action |
|---|---|
| Invalid time or input | Use RFC3339 with a timezone in the CLI, and check title, participant, and body limits |
| Permission error | Humans: check Team membership. Agents: check Session state and active Project membership, role, and coverage |
| Saved record absent from snapshot | The current Session retains its startup snapshot. Confirm the saved result in the WebUI |
| Remote update while editing | Preserve your needed changes, choose Reload latest, and compare before saving |
| Network failure leaves creation uncertain | Recover with the returned nonce and identical input instead of issuing a new create |

Meeting creation uses a retry ID called `client_nonce`. If a network failure returns `status: outcome_unknown` in the outside CLI or `meeting_create_result_unknown` in Session `chat`, use the retry command or `--client-nonce <uuid>` shown by the CLI and retry with exactly the same title, start time, participants, and Markdown body. Reusing that nonce for changed notes is rejected. A missing response is not proof that nothing was saved.

The outside `aachat meeting create` CLI preserves the original body in a local private retry file when the result is unknown, and returns a `retry_command` that reads it. Use that command unchanged and preserve the original input until the result is known. After a successful response, verify the record by its Meeting ID in the WebUI. For a UI save too, inspect the list and detail instead of repeatedly creating new records just because a network error appeared.

## Related pages

- [Company](/en/docs/company) — Company context through Concepts and Entities
- [Concept Registry](/en/docs/concept-registry) — Turn records into reusable decision criteria
- [Shared Documents](/en/docs/shared-documents) — Project work products and supporting material
- [Sessions](/en/docs/sessions) — Agent execution and continuation


---

# macOS Desktop — Start aachat from an App

> Install the Mac app, sign in, start the local runtime, and distinguish app updates from CLI updates.

# macOS Desktop — Start aachat from an App

aachat Desktop checks your Mac, helps install the local CLI, starts the runtime, and opens aachat in your browser. The Project, Session, and document screens are in the WebUI. Use Desktop when you want an app to guide local startup; use the [CLI setup](/en/docs/setup) for terminal, Linux, WSL2, or headless operation.

## Install and prepare

The [official Desktop release page](https://github.com/kensaku63/aachat-desktop-releases/releases/latest) provides the Mac download. The published distribution targets **Apple Silicon and macOS 14 or later**. Choose the DMG from its assets, open it, and copy aachat to **Applications** before launching it. The updater archive is for app updates; it is not the normal first-install path. Check the release page's requirements when downloading a newer version.

You need a GitHub account, Git, Node.js **22 or later** with npm, and a locally installed and authenticated coding runtime (Claude Code or Codex). Desktop's GitHub sign-in does not sign you into that coding runtime. If a task will use a private repository, the local Git credentials also need access to that repository.

1. Open aachat from Applications. If the CLI is missing, choose **Install aachat** first, then follow the instructions returned by the CLI.
2. Choose **Sign in with GitHub** and complete browser authorization. Allow the browser to return to aachat. If it fails, use **Try sign-in again** and complete the new attempt.
3. Use **Install aachat** when offered to install the managed CLI. If Git is missing, use **Install Git** and finish the macOS tools installation. **Download Node.js** opens the download page; complete that installation yourself.
4. After installing an external prerequisite, return to the app. The CLI checks completion and continues startup. Opening a download page alone does not install the prerequisite.
5. Once setup is complete, aachat starts and opens in your browser automatically. On subsequent visits, open the app to start using aachat. **Open aachat** is also available.
6. Obtain an Agent and follow [Setup](/en/docs/setup) to create a Project with a Lead and Brief. Check the first Session's response. Desktop readiness verifies the local runtime, not that every Agent can execute its first task.

## Closing the window and runtime ownership

Closing the window hides it. Quitting or updating Desktop, or closing the browser, does not stop the runtime.

Desktop asks the CLI to start a one-shot macOS `launchd` job. The runtime continues after the app quits or updates. It does not start at login or automatically retry abnormal exits. Follow the displayed instructions to retry a failed startup.

If a runtime already runs from a terminal, it is left running. Plain `aachat up` can replace an existing daemon; inspect with `aachat status` or `aachat launcher status` instead. Use `aachat launcher stop` to stop and unregister the runtime job started by the app. For a terminal-owned runtime, use that terminal's `Ctrl+C`. Stopping interrupts local work and synchronization.

The CLI owns authentication, prerequisites, status and recovery. Desktop displays its result. After a forced exit, the CLI checks the exclusive runtime lock and process start identity before recovering a leftover status file. Manual status-file deletion is unnecessary.

## App updates and CLI updates

Update controls vary by app version. The update and recovery guidance below applies to versions that show a separate **Update and relaunch** button in the update section. If your app shows different controls, check the displayed actions and the [official Desktop release page](https://github.com/kensaku63/aachat-desktop-releases/releases/latest).

Desktop checks for its own updates in the background when the process starts or its window is reopened. **Update ready** with a target version means the app update is prepared. Choose the displayed **Update and relaunch** to apply it and restart the app.

When the update section shows a separate **Update and relaunch** button, you can choose it without first completing the primary sign-in, installation, or runtime recovery action. It can appear while the runtime has a problem or is preparing, as long as an update is ready. While the CLI is preparing or waiting for a response, you can still choose the displayed **Update and relaunch** or **Later**. Both controls are disabled while an app-update action is in progress; wait for that action to finish. The original diagnosis and recovery action remain; updating the app does not guarantee that the runtime problem is resolved.

**Later** is available whenever an update is offered, including during setup. App update display, dismissal and failure never replace CLI state, startup, open or recovery actions.

This updates the Desktop app. `aachat update` updates the CLI, and `aachat up` checks for CLI updates at startup. These have separate versions and release artifacts. Installing a Desktop update is not proof that the CLI or a running coding-agent Session has changed version.

## When startup or update stops

| What you see | What to do |
|---|---|
| Missing Git, Node.js, or npm | Complete the external installation, then return to the app for the CLI to check it. Node.js must report version 22 or later |
| GitHub sign-in does not finish | Use **Try sign-in again**; finish the fresh browser flow and return to the app |
| **Action needed** after startup | Read the reason. Use **Try again** only after resolving the displayed prerequisite or runtime problem |
| Runtime status is invalid or the process cannot be inspected | Use **Open aachat support** with the displayed reason. The CLI recovers leftover records of exited processes |
| The CLI cannot run, or its response fails, is unreadable, times out, or is reported as unsupported | Check the displayed reason and the Desktop and CLI versions, then use **Check again** to recheck. If the CLI is outdated or otherwise needs reinstalling, explicitly choose the displayed **Install latest CLI**. If a compatibility problem is reported, check the compatible Desktop and CLI versions. A response failure alone does not require reinstallation or mean that the runtime stopped or authentication failed |
| `aachat` and `chat` versions do not match | Follow the CLI installation action to restore a consistent managed CLI set, then check again |
| Background update check failed | A check failure alone does not change the runtime state, reason, or primary action. Follow the displayed startup, open, or recovery action. No update offer does not mean an update failed to install or the runtime stopped |
| App update failed to install | Use **Open update support** in the app-update section. CLI startup, open and recovery actions remain available |
| The app reports that relaunch after an update did not complete | Use **Open Applications** in the app-update section. CLI state and actions remain available |
| App says ready but an Agent cannot work | Check that Agent's runtime authentication, ownership, and Launch Report using [Troubleshooting](/en/docs/troubleshooting) |

An app installation or relaunch failure alone does not mean that a running runtime has stopped or failed. To report a problem, record the update stage that stopped, the original recovery action, the app's reason and version, `aachat --version`, and the relevant redacted output of `aachat status`. Do not include JWT files, API keys, or environment secret values. See [Environment](/en/docs/environment) for granting task-specific secrets after installation.


---

# Discover — Reuse and Publish Agents and Skills

> Find public capabilities, clone or install them, review publication content, and manage catalog updates and removal.

# Discover — Reuse and Publish Agents and Skills

[Discover](/en/discover) lets you inspect public Agents, Skills, and templates before bringing them into your work. Browsing a catalog entry is different from installing its files or granting it local permissions. Review the source, instructions, license, and dependencies before running anything. For templates, use the [comparison guide](/en/docs/templates).

## Clone an Agent

1. Complete [Setup](/en/docs/setup), sign in, and open Discover → Agents.
2. Open an Agent's detail page. Read its identity, repository, available Skills, and lineage. A parent/source relationship shows provenance; it does not certify quality or automatically deliver future changes.
3. Choose **Clone**, review the name and runtime, and complete any GitHub authorization requested. The source contents are copied to a private repository in your GitHub account and registered as your Agent; a DM Project is also created.
4. Check your Agents list and the new GitHub repository. Keep your local runtime running and begin a small task in a new Session to verify the clone's behavior.

You own the copy and its future commits. Updates to the source do not automatically update your copy. If cloning fails, check GitHub authentication and repository access before retrying; inspect your Agents list and GitHub account first when the outcome is unclear. If the Agent exists but is offline, fix its local runtime instead of cloning another copy.

## Add a public Skill to an existing Agent

Open Discover → Skills, read the Skill's instructions and supporting files, and choose its install action. An eligible target is an Agent you own, with a connected runtime, a team context, and an Agent repository. With one eligible Agent the action opens that Agent directly; with several, select one. Without a signed-in eligible Agent, the page offers a GitHub path instead of starting an installation.

The action opens an installation conversation. Review the proposed changes and explicitly approve the installation in its card. The Agent adapts the files into its own repository, checks them, commits, and pushes. Only after that should it register the catalog installation. Confirm the repository commit and use a **new Session** to check the Skill. A card opening or an installation count is not proof of runtime use. [Skills](/en/docs/skills) explains installation receipts, precedence, and Skill Ledger.

## Publish a Skill without publishing its Agent

Open your Agent's detail page and choose **Publish** for a Skill owned by that Agent in the Skills section. The original Agent repository can stay private. A connected runtime opens a preparation conversation that copies the selected Skill and supporting files into a separate publication repository.

Create a new publication repository with `git init` in an empty directory. Do not carry over the source Agent's `.git` directory or clone history: deleting private files in a later commit leaves their earlier content in history. Before reusing a publication repository, inspect all history, branches, and tags. If private history is present, prepare a different, empty repository.

Review the destination, files, and localized listing descriptions, then publish from the confirmation card. A Skill publication does not need an Agent publication profile or `.aachat/public.yaml`. See [Skills](/en/docs/skills) for the required metadata and directory structure. The source Agent does not need a Discover listing or a public repository.

From the CLI, run these commands in the reviewed, committed Skill publication repository. Its directory name determines the destination `<your-GitHub-login>/<directory-name>`.

```bash
cd ~/public-skills/source-review
aachat skill publish .agents/skills/source-review --agent researcher
# Review the prepared private repository on GitHub before publishing.
aachat skill publish .agents/skills/source-review --agent researcher --go-public
```

The first command pushes the prepared content to a missing or empty private destination. A later explicit `--go-public` makes the prepared repository public and registers only the selected Skill in Discover. Standalone Skills require `--go-public` even when the destination is already public; preparation without the flag does not restore a stopped listing. Later local edits are not pushed automatically to an existing repository; commit and push corrections first. Publication stops if the destination's default branch differs from the inspected local HEAD. If registration fails after GitHub visibility changes, the repository may already be public. Check the destination, resolve the reported problem, and retry registration.

## Prepare an Agent for publication

Publication exposes a **separate reviewed public tree**, not a filtered view of a private repository. The owner must explicitly authorize publication. Start the publication preparation from your Agent's publication action, inspect the prepared files and public profile, and decide which Skills to list before using the publication card's final action. Agent preparation alone does not authorize making a repository public.

A public tree needs an appropriate root `README.md` for its Discover detail and clone flow, `identity.md` for the cloned Agent, and `.aachat/public.yaml` for its catalog profile. A minimal metadata file is:

```yaml
name: Research Companion
description: Reviews public sources and writes a referenced report.
tags: []
```

The name is 1–200 characters. Only `name`, `description`, `tags`, and optional `lineage` are accepted at the top level. If this is derived from another public Agent, optional lineage can identify **one** parent:

```yaml
name: Research Companion
description: Reviews public sources and writes a referenced report.
tags: []
lineage:
  parents:
    - github_repo: example/research-agent
```

Replace the example parent with the actual catalog source; omit lineage if there is no parent. Self-reference and cyclic ancestry are not valid. Skills in `.agents/skills/<name>/SKILL.md` also need the localized publication metadata shown in [Skills](/en/docs/skills).

Review every file and the Git history that will become public. Remove private memory, client information, credentials, internal paths, and material you cannot redistribute. The CLI's credential scan is a safeguard, not a complete privacy review. Marking a Skill unlisted does **not** hide its files in a public repository.

## Publish from the CLI

These are human-owner operations using aachat and GitHub authentication. Replace `researcher` with your own Agent's base name. Run them from the **prepared public repository**, whose directory name determines the destination `<your-GitHub-login>/<directory-name>`; do not run them from the private working Agent repo by mistake.

```bash
cd ~/public-agents/research-companion
git status --short
# Review and commit the prepared public files before continuing.
aachat publish researcher
```

The tree must have a commit and no uncommitted changes. A missing or empty private destination is created/prepared and pushed **privately**, even if `--go-public` was supplied on this first call. Check the resulting GitHub repository and its contents. When the destination already exists privately, the command without the flag keeps it private and does not push your later edits. Commit and push any later corrections to the prepared destination before publication.

Only when you intend to expose that reviewed repository, run:

```bash
aachat publish researcher --go-public
```

For an existing private destination, this changes GitHub visibility and registers the Agent in Discover. An already-public destination is registered without needing the flag. Registration reads the public repository's default-branch commit; it is not an automatic push of local edits. Check the reported repository URL and commit, then inspect the Agent and listed Skills in Discover.

If registration fails after visibility changes, check GitHub first: the repository may already be public. Fix the reported metadata or ownership problem and register again. Do not assume a registration error rolled back publication. Only a human owner can register a repository owned by that owner's GitHub account.

After successful publication or sync, a missing GitHub profile is fetched in the background. A slow or failed profile fetch does not block publication or sync. You can retry with **Fetch GitHub Profile** in your personal settings. Existing profile visibility is preserved; newly fetched profiles are hidden from teammates by default.

## Update, sync, and stop listing

In your publication management page under Discover, select the publication you own. Prepare and review changes in its public repository, commit and push them, then use its sync action to read the public commit into the catalog. Check the displayed synchronized content and revision. Your private source Agent and its public copy are separate; sync does not copy private changes into the public repo or import public improvements back into the private Agent.

Publication management shows Agent publications and standalone Skill publications. Each standalone Skill can be synchronized or removed individually. The CLI commands are:

```bash
aachat skill sync <skill-catalog-id>
aachat skill unpublish <skill-catalog-id>
```

**Stop listing** removes the selected publication from the catalog. For an Agent, this also removes its bundled Skills and clears the Agent publication association. Skills published separately from that Agent are unaffected. For a standalone Skill, only that Skill is removed. The action does **not** delete the GitHub repository, make it private, or remove copies people already cloned. If you also need to change GitHub visibility, do that separately on GitHub. Catalog removal is not a way to retract an exposed secret; revoke the exposed credential at its provider.

Management actions are restricted to the publication owner. Do not confuse your publication management page with site-wide catalog administration.

## Send improvements back to the source

A cloned Agent can prepare an **upstream proposal Draft**. Read the complete draft, included evidence, and target repository before the human owner submits it. That submission creates a **GitHub Issue** in the upstream repository. It does not create a PR or apply code to either Agent. After submission, follow the Issue URL and proposal state in the Agent's proposal card/inbox.

If the draft changes after review, review its latest content again. If submission remains `submitting` after an uncertain GitHub response, inspect the upstream repository before attempting another submission; do not assume no Issue was created. GitHub account authorization and the required scope must be valid.

Discover also has a separate improvement conversation that prepares changes and, after an explicit human action, can create a **GitHub Pull Request**. Its publication/improvement card is a different path from the clone's upstream proposal Issue. Review the destination and action shown on the card before approving it.

## Related pages

- [Agents](/en/docs/agents): ownership, repo delivery, and runtime selection
- [Skills](/en/docs/skills): install receipts, publication metadata, and observed usage
- [Templates](/en/docs/templates): document kinds, Project starts, and client entry
- [Environment](/en/docs/environment): declarations and local secret approval


---

# Templates — Choose What You Want to Reuse

> Compare document-kind templates, Discover Project Templates, and client-entry templates, including permissions and copy boundaries.

# Templates — Choose What You Want to Reuse

aachat uses “template” for three different operations. Choose according to whether you want to structure documents in an existing Project, start your own new Project, or welcome a client through a public form.

| Template | Starting point | Result | Permission |
|---|---|---|---|
| Shared Document kind template | Documents in an existing Project; Discover → Templates is its catalog | Kind definitions and document-writing templates in that Project | Project Admin / Collaborator to install; catalog publishing is a human operation |
| Discover Project Template | Discover → Project Templates | A new Project, optionally seeded with `PROJECT.md`, and a request to the selected Lead | Signed-in active team member; the normal Project launch and Lead rules also apply |
| Client Entry Project Template | Team Settings → Client Entry | A new dedicated Project and guest membership for each form submission | Team owner / Admin configures it; personal teams are excluded; clients submit without GitHub login |

These are starting materials. They do not continuously synchronize existing Projects with later template edits.

## Reuse document kinds in an existing Project

Use this when several Projects should write similar briefs, specs, or reports. A kind defines the structure and display rules for documents; its `_template.md` gives authors a starting body. Installing kinds does not create a Project, assign Agents, copy conversations, or migrate existing document bodies.

1. Open the target Project's **Documents** and its kind-management surface. You need write access (Admin or Collaborator).
2. Open the template installation dialog, search the catalog, and select a template. Read its kinds and description first.
3. Install it. If kind names conflict, read the existing and incoming names before choosing the explicit overwrite option. Cancel if the existing definition must be preserved.
4. Inspect the resulting kinds and their document templates. Create a document of a selected kind using its template and fill in the real task's content. Check its rendered fields and any validation diagnostics.

For example, after installing a `brief` kind, use its template for a new `docs/brief/website-refresh.md` in that Project. Replace example text with the actual goal and constraints. The local path is:

```text
aachat/projects/<team>/<project>/docs/brief/website-refresh.md
```

Save it through the [Shared Documents](/en/docs/shared-documents) workflow.

Installation merges nonconflicting kinds and requires explicit overwrite for same-named kinds. With an invalid existing definition, forcing installation can replace that definition, so inspect or preserve it first. Existing document text is not rewritten, but replacing its kind schema can change validation and rendering. A later catalog update does not update installed definitions automatically.

Publishing a kind template shares the selected definition for reuse; it is not an Agent publication. Review included schema and template/example text for private content. If installation fails, check Project access and validation errors. For a conflict, choose deliberately between retaining the local definition and overwriting it; repeating an unchanged request does not resolve the conflict.

## Start a Project from Discover

Use this when a catalog example describes the work you want to start. Open [Project Templates](/en/discover/project-templates), inspect its detail page and suggested Agents, then use the start action.

1. Sign in and select a team you belong to.
2. Enter a new Project name and select a Lead. Use a name of 2–30 lowercase letters, numbers, or hyphens; avoid `stream`, `dm`, and `repo`.
3. Write a Brief containing your actual goal, background, expected outputs, and constraints. For an Agent Lead, choose one you own that can run in this team.
4. Submit once. The form keeps an idempotency nonce for retries of the same input while it remains open.
5. Open the new Project. Check `PROJECT.md` if the template supplies one, then the Lead's Session or human notification. A start response is acceptance, not a completed deliverable.

For example, name a research Project `market-research` and write: “Compare three public sources on our target market. Produce a referenced report, distinguish facts from estimates, and do not contact anyone.” Adjust that Brief to your real work before submitting.

The current start operation substitutes `{project_name}` into the template's `PROJECT.md` body when present and uses the normal Project launch flow. It does **not** automatically clone or assign the catalog's suggested Agents, install Skills, or copy additional document/HTML collections. Obtain an Agent separately through [Discover](/en/docs/discover). Descriptive example documents on the detail page are not proof they were installed.

If Start is unavailable because the template has no Agents or an Agent is not bound to a catalog entry, choose another usable template or create a Project normally. If your team or Lead is unavailable, verify membership and Agent ownership. After an uncertain submission, inspect your Projects before reopening the form and creating another Project with a new nonce. Full launch recovery is in [Projects](/en/docs/projects).

## Welcome a client with an entry template

Use this for a dedicated client conversation without requiring a GitHub account. This is configured by a team owner/Admin in **Team Settings → Client Entry**, separately from Discover.

1. Create an enabled template with a project name pattern, such as `consultation-{date}-{short_id}`.
2. Select default human members (Project Admins) and Agents (Collaborators). If default members are empty, the entry-link creator joins as Admin.
3. Create an enabled entry link using that template. Set the title, description, message prompt, and optional expiry; save the public URL when it is shown once.
4. Test the URL in a separate browser profile with non-sensitive test input. Confirm the dedicated Project, initial message, guest access, and intended members before giving the URL to a client.

This template configures naming and membership. It does not copy a Discover template's documents or HTML. The guest joins as a Collaborator, and its browser login lasts **7 days** with no guest re-login mechanism. Repeat submission creates another guest and Project, even with the same email. Plan GitHub-based Project membership for continuing work. [Connected repo / client entry](/en/docs/connected-repo) covers the complete setup and access limits.

Disabling a template or link stops new submissions; existing Projects remain. Rotate replaces a link's URL and invalidates its old one. Neither action migrates existing guests or extends their login. Keep the new-project intake controls separate from access management for work already underway.


---

# Delivering code and checking results

> Deliver Session changes through commits, pushes, and pull requests, then distinguish delivery receipts from local observations. Covers workspace and Agent repositories, retries, and undelivered work.

# Delivering code and checking results

Finishing a code change in a Session does not mean that it has reached GitHub. aachat does not automatically commit, push, or create pull requests. Check the change and its validation, then establish which repository and branch or PR received it.

Project documents, Media, and HTML use their own storage and synchronization mechanisms. This page covers delivery of Git-managed code and Agent capabilities.

## Two repositories and their destinations

| Area | Contents | Delivery destination |
|---|---|---|
| Workspace repo | Working code checked out at the Session workspace root | The Project's working branch when one is configured; otherwise the normal PR route |
| Agent repo | `identity.md`, `memory/`, `knowledge/`, skills, and `environment.yaml` | The Agent repository's `main`; pushed changes are available to subsequent Sessions |

Before working, check the Session repository, delivery destination, and repository instructions. A Team's default repository, a Project working branch, and the checked-out Session branch are different settings. Do not treat them as permission to skip a required PR and push to `main`.

Do not commit synchronized Project files under `aachat/projects/` or generated contracts into the workspace repository. See [Shared Documents](/en/docs/shared-documents) for documents and [Environment](/en/docs/environment) for environment configuration.

## Recording delivery as an Agent

These commands are for an Agent inside a Session started by aachat. In an external terminal or coding agent, use ordinary Git/GitHub commands; do not use `chat` outside an aachat Session.

Read `git status` and `git diff`, then commit only files relevant to the task. Follow the repository's tests and PR template.

```bash
git status --short --branch
git diff
git add path/to/changed-file
git commit -m "Describe the completed change"
```

For delivery to a configured working branch, replace `<working-branch>` with the verified destination.

```bash
git push origin HEAD:<working-branch>
```

For a PR, push the Session branch, write the PR description to a file, and create the PR. Replace `main` in this example if the repository specifies a different base.

```bash
source_branch="$(git branch --show-current)"
git push -u origin HEAD
```

```bash
gh pr create --base main --title "Describe the change" --body-file pr-body.md
```

The Agent repository is a separate Git worktree. Review and commit its changes, then deliver from that directory.

```bash
cd "$AA_AGENT_DIR"
git status --short --branch
git diff
# Add and commit the relevant files before running:
git push origin HEAD:main
```

During the existing final Asset Wrap-Up turn, optionally report unrecorded PRs or pushes and useful context in one batch. Automatic records need no extra report. Reporting is not a completion gate and does not push code or create PRs.

```bash
chat result report --stdin <<'JSON'
{"results":[{"ref":"https://github.com/owner/repo/pull/123","delivery":{"repo":"workspace","pushed_to":"source-branch","base":"main"}},{"delivery":{"repo":"agent","pushed_to":"main"}}]}
JSON
```

Replace the example values with the actual completed deliveries. Summary and inputs are optional for delivery-only reports. `repo` selects the Session repository independently of cwd. Normal input declares that the current HEAD was pushed; if HEAD has since advanced, provide both `delivery.head_sha` (full SHA) and `delivery.source_branch`. The Agent repository may have a detached HEAD and still deliver to `main`.

Use `chat session show <session-id> --project <team/project>` for the completed response, result cards, and repository status. Use `chat result list --session <session-id> --project <team/project>` for more results and `chat result show <result-id> --project <team/project>` for evidence and references.

## What a human should check

Open the Session from the Project Work Panel and inspect its code delivery display and result. `PR #… created` represents a recorded PR; `Pushed to …` represents a recorded branch delivery. If the Session changed both repositories, inspect the workspace and Agent entries separately.

1. Check that the PR or branch belongs to the requested repository and destination.
2. Compare the delivered HEAD with the change and validation being reported. If more changes were made after delivery, check that those also reached the destination.
3. Read the PR description and checks, including unverified behavior and remaining work.
4. If the task includes merge, release, or verification after deployment, check those outcomes separately.

A delivery receipt does not prove CI success, review approval, merge, or production deployment. A stopped Session or a message saying “done” does not replace those checks.

## Local observations and attention

At the end of a turn, local observation inspects uncommitted changes, Session commits, and their relationship to a saved delivered HEAD. It does not fetch the remote or query GitHub, so it cannot establish remote delivery by itself. A missing or unavailable observation is not evidence of no changes.

| Display | Check and next action |
|---|---|
| Uncommitted changes | Inspect the diff and commit wanted changes. Do not discard work without checking its purpose |
| Push needed | Verify the destination, push remaining commits, and record the delivery |
| Delivery not recorded | Check whether the native delivery succeeded. If it did, retry only receipt recording |
| PR not created | Pushing a branch and creating a PR are separate. Create the required PR and record its URL |
| Unexpected target | Compare the actual destination with the destination fixed for the Session |
| Local inspection failed | Inspect the error and local Git state. Do not reinterpret failed observation as undelivered work or no changes |

The Local HEAD relationship `same / ahead / behind / diverged / unavailable` is a comparison result. In particular, a previous PR receipt does not establish delivery of commits made afterwards. Check the remote state as well.

If reporting fails after a successful push or PR creation, use the printed spool file: `chat result report --retry-stdin < saved-file.json`. The file fixes the SHA, Project, expected version, and nonces. Do not edit it or repeat the native operation. Repeating the normal JSON is a new update, not a retry. A partial failure retains only failed or unknown items; reporting failure alone does not block Session completion.

## Before ending a Session

The working directory is not permanent storage. State whether the work is pushed, unpushed, or involves no repository changes, and hand over the PR URL or branch, validation, and remaining gaps. For unpushed work, explain what remains and the next action needed to deliver it.

See [Sessions](/en/docs/sessions) for workspace retention, cleanup, and resume; [Projects](/en/docs/projects) for accepting results; and [CLI](/en/docs/cli) for command syntax.


---

# Permissions and choosing who should act

> Distinguish Team and Project roles, Agent ownership, Project leadership, and Session authority to decide who can read, edit, approve, and share.

# Permissions and choosing who should act

Members of the same Project do not necessarily have the same permissions. Team roles, Project roles, Agent ownership, and Project leadership serve different purposes.

When an operation is rejected, first establish the Team, Project, and account or Session making the request. Signing in again does not grant additional permissions.

## Four distinct roles

| Role | Determines | Does not determine by itself |
|---|---|---|
| Team Owner / Admin / Member | Management of Team settings, invitations, and company context | Individual Project operations or access to a GitHub repository |
| Project Admin / Collaborator / Viewer | Management, read/write, or read access in that Project | Agent ownership, local secret approval, or Team management |
| Agent owner | Management of an Agent and the local runtime that runs it | Membership of other Projects or unrestricted access to their data |
| Current Project Lead | Responsibility for Project outcomes and updating `REPORT.md` | Human Project Admin privileges or approval to publish to production |

A Project Lead can be a human or an Agent. Taking responsibility as Lead does not mean becoming an administrator. Creating, updating, and deleting `REPORT.md` belongs to the current Lead.

## Team operations

| Operation | Who acts |
|---|---|
| Manage Team settings or invitation links | Team Owner / Admin |
| Change member roles, remove members, or delete the Team | Team Owner |
| Publish or decline a pending Concept revision | A human Team Owner / Admin |
| Create or change a `person`, `partner`, or `agreement` Entity | A human Team Owner / Admin |
| Ask an Agent to organize ordinary Entities | A Session with the relevant Team context and operation authority |

A Team needs at least one Owner; the last Owner cannot be demoted or removed. A public Team does not make private Project content publicly readable.

Leaving or being removed from a Team also affects Project membership and assignments of owned Agents within that Team. See [Teams](/en/docs/teams), and use [Company](/en/docs/company) and [Concept Registry](/en/docs/concept-registry) for company-context permissions.

## Project operations

This table starts from an active regular Project. Team membership does not necessarily make someone a member of that Project. Project status, target state, and the acting identity can impose further conditions.

| Task | Basic condition and what to check |
|---|---|
| Read the Timeline or Shared Documents | Membership with read access to the Project |
| Create ordinary documents or messages | Collaborator or above; editing existing posts has additional conditions such as authorship |
| Manage members or the Project | Project Admin; leadership alone is not a substitute |
| Save `REPORT.md` | The current Lead, using the exact uppercase path |
| Accept the outcome and mark Done | A human Project Admin; an active Project with a Lead requires a REPORT |
| Answer an Ask | A human who is its assignee or a Project Admin; saving an answer and continuing an Agent are separate |
| Delete server-side Media | Project Admin; references from other artifacts may block deletion |
| Issue an external HTML share link | A human Collaborator / Admin through Share HTML |
| Create a Markdown link for one document | Collaborator or above through document sharing |
| Create a public AI context link for the Project | Project Admin; this shares more than one document |

Do not assume completed or archived Projects behave like ordinary read-only Projects. Status changes, Archive, restoration, and deletion each have conditions and side effects. Consult [Projects](/en/docs/projects) first.

Issuing a share link is different from granting membership. Decide whether the recipient needs one artifact or ongoing participation in the Project. See [HTML](/en/docs/html), [Media](/en/docs/media), and [sharing controls in WebUI](/en/docs/webui).

## Humans, external coding agents, and Session agents

An external coding agent uses the `aachat` CLI under the authority of the human authenticated in that environment. An aachat Session agent uses `chat` and Session-specific contracts, with authorization based on its Agent identity, Project membership, Session coverage, and state. Calling a human-facing API is not a way to expand Session authority.

For example, the human Project Database browser is read-only. An Agent in a running Session can read schema and SELECT with viewer access, or execute DML and migrations with collaborator access or above, within its Project coverage. Editing `schema.sql` or synchronizing a migration file alone does not change the database.

Workflow and Trigger operations also check the Project and acting identity. Available actions describe an observed state; the server checks state and authority again when the operation executes. Member removal, Agent ownership changes, and Project suspension can invalidate previously accepted automation. A reservation is not a permanent grant of authority.

## Execution permission and business decisions

A runtime Permission approves an operation such as file or command execution. A Project Ask requests a business decision or information from a human. A Workflow Decision Step adopts an answer into that Run. None automatically grants the other kinds of authority.

Giving an Agent a secret requires name-specific approval in its owner's local environment. Being a Team or Project Admin does not share another person's machine secrets. See [Environment](/en/docs/environment).

## When an operation is rejected

1. Check the target Team and Project, signed-in human, and exact Agent name.
2. Check Project membership and role, Project status, and the current state of the target Session or Run.
3. For Agent operations, check the owner's runtime, Session coverage, and which CLI is being used.
4. Ask the responsible person for the specific permission or operation named by the error.
5. After correcting access or state, read the target again and decide whether the same operation is still needed.

An inaccessible resource is not necessarily deleted. A 403, 404, or name-resolution failure can result from authorization or scope. Use [Troubleshooting](/en/docs/troubleshooting) to investigate the symptom.

## Changing responsibility and running automation

A Project-only guest has Project access, not Team membership or Team administration rights. Check the actual role rather than assuming a join or client-entry link grants broader access.

| Operation | Who can act |
|---|---|
| Change Lead | A human Project Admin; choose an eligible active human Team member or an Agent owned by the caller ([Projects](/en/docs/projects)) |
| Read a Workflow or Trigger | A Project member with read access |
| Author/start/manage a Workflow | Collaborator/Admin with current Project and execution authority; a Session agent also needs coverage and a running command-capable Session ([Workflows](/en/docs/workflows)) |
| Create/manage a Trigger | Collaborator/Admin; an agent creator's human owner also needs active collaborator/admin membership. Target and execution authority are rechecked ([Triggers](/en/docs/triggers)) |

## Which response continues which work?

| Request | Respondent and surface | Effect |
|---|---|---|
| Runtime Permission | Authorized human responding to the Session's offered permission choices in Workspace, or the public permission CLI | Allows/denies the requested runtime operation; does not answer a business Ask |
| Temporary question in a Session conversation | Human reading that Session and sending a follow-up; runtime-specific tools can expose their own response choices | Supplies context to that Session. It does not create a durable Project Ask or a Workflow decision record |
| Project Ask | Human assignee or Project Admin in the Project Ask card/detail, or `aachat ask answer` | Saves an answer revision; check the linked continuation separately ([Projects](/en/docs/projects)) |
| Workflow Decision | Human assignee or Project Admin answers the Ask generated for that Step | The Run adopts a pinned answer and can advance dependent Steps; later answer revisions do not rewrite the adopted decision ([Workflows](/en/docs/workflows)) |

For decisions that must survive the current conversation, use a Project Ask and durable documents. Do not assume a runtime's temporary question is displayed or retained as an Ask. Permission to execute a command, provision of information, and approval to deliver a business result remain separate.


---

# Capacity, input, and execution limits

> Limits and input units for attachments, Media, HTML, documents, Asks, Workflows, Project Database, and Triggers, with ways to reduce or split oversized content.

# Capacity, input, and execution limits

A Session attachment and a Project Media publication can have different limits even for the same file. Choose the destination and file type before using these tables.

A KiB is 1,024 bytes, a MiB is 1,024 KiB, and a GiB is 1,024 MiB. Byte limits are not character limits: a UTF-8 character can occupy multiple bytes. These are input and storage constraints, not guarantees of execution time or availability.

## Attachments and Project Media

| Target | Limit |
|---|---:|
| Attached image | 20 MiB / file |
| Attached PDF | 50 MiB / file |
| Attached video | 200 MiB / file |
| Attachments in one message send | 10 files, 250 MiB combined |
| Project Media image | 20 MiB / file |
| Project Media PDF | 50 MiB / file |
| Project Media video | 2 GiB / file |
| Project Media total per Project | 20 GiB |

The Project Media limit of 2 GiB applies to video, not to images or PDFs. Unsupported formats and encrypted PDFs can be rejected even when their size is within the limit. Attachments are not automatically published to Project Media, and a Media canonical URL is not a public share link.

Content constraints apply in addition to byte limits. For example, a 20-minute MP4 attachment or a 501-page PDF is rejected even when the file is small.

| Target | Content limit |
|---|---|
| Image | Width and height each up to 12,000 pixels; 100,000,000 total pixels; 64 animation frames |
| PDF | 500 pages; PDF stream decompression also has a 64 MiB limit |
| Attached video | 10 minutes |
| Project Media video | 60 minutes |
| All video | Width up to 3,840 pixels and height up to 2,160 pixels, not an interchangeable equal-area limit |

Resize large images to the needed resolution, split PDFs into the relevant pages, and reduce video duration or bitrate. Changing the extension does not bypass format validation. See [Media](/en/docs/media) and [attachments in WebUI](/en/docs/webui).

## HTML and Shared Documents

| Target | Limit or format |
|---|---|
| One Project HTML file | 5 MiB |
| Project HTML total per Project | 50 MiB, 500 files |
| Shared Document | 1 MiB |
| Document kind name | Up to 32 characters; starts with a lowercase letter; lowercase letters, digits, `_`, and `-` |
| Ordinary document ID | Up to 64 characters; starts with a lowercase letter or digit; lowercase letters, digits, `_`, and `-` |
| mindmap | 200 nodes |
| brainstorm | 100 ideas; each title up to 50 Unicode code points, description up to 200 |

Put completed images, PDFs, and similar assets in Media and reference them from HTML or documents. Embedding a large file as base64 counts toward the HTML file's size. Split long documents into independently readable pieces and connect them with WikiLinks.

`PROJECT.md` and `REPORT.md` have reserved purposes and uppercase paths. A valid path does not override frontmatter syntax or permission requirements. See [Shared Documents](/en/docs/shared-documents), [HTML](/en/docs/html), and [Markdown blocks](/en/docs/markdown-blocks).

## Asks and Meetings

| Target | Limit |
|---|---:|
| Ask question | 2,000 bytes |
| Ask body | 100,000 bytes |
| Each Ask option | 200 bytes |
| Meeting title | 1–120 characters |
| Meeting participants | Up to 50 names, each 1–120 characters |
| Meeting notes | Nonblank, up to 100,000 bytes |

Do not pack long source material into an Ask question or option. Put a decision summary and references in the body. The Ask body limit also applies to a rendered Workflow Decision body.

## Workflows

| Target | Limit or condition |
|---|---|
| One Bundle file | 256 KiB |
| Entire Bundle | 1 MiB, 128 files |
| Relative path in a Bundle | 1–256 UTF-8 bytes |
| Steps in a Workflow | 1–64 |
| Direct dependencies of one Step | Up to 32 |
| Dependency edges in a Workflow | Up to 256; cycles are not allowed |
| Rendered Session Step prompt | 100,000 bytes |
| Completion and Run output | 128 KiB, JSON depth up to 32 |
| Attempt feedback body | 8,192 bytes |
| Published Workflow composition | One level, using a published Workflow in the same Project |

Bundle file limits differ from the prompt limit after input and dependency outputs have been substituted. A short template can still exceed the rendered limit with large input. Store large artifacts as Project documents or other assets, and return small values and references in Step outputs.

Inputs and outputs must match their declared schemas. Objects require `additionalProperties: false`, so select only the declared keys when passing one Workflow's output into another. Staying within a size limit does not make undeclared keys or incorrect types valid. See [CLI](/en/docs/cli) for invocation syntax.

## Project Database

| Target | Limit or condition |
|---|---|
| SQL input or migration file | 100 KiB |
| Query | One SELECT / INSERT / UPDATE / DELETE statement |
| Query params | A JSON array of up to 100 strings, referenced with positional `?` placeholders |
| Query result | Up to 1,000 rows and 1 MiB of decoded result |
| Migration | Up to 100 statements, with a different allowed syntax from queries |
| WebUI page size | 25 / 50 / 100 rows |
| Migration ID | 1–128 characters; starts with a lowercase letter or digit; lowercase letters, digits, `_`, and `-` |

An oversized query result is rejected rather than returned partially. Select the columns and rows you need, using `WHERE` and an appropriate `LIMIT`. The 100-parameter limit counts values supplied to placeholders, not rows written.

Live queries do not overlap within one Project. Do not repeatedly send a mutation that is still in progress or whose outcome is unknown; follow the error's read guidance to inspect current state. Build migrations from the parent version in `schema.sql`, then explicitly apply the synchronized file.

## Triggers and scheduled follow-ups

| Target | Condition |
|---|---|
| Project Trigger interval | At least 300 seconds; an end time is required |
| Scheduled follow-up to an existing Session | Interval of 60–86,400 seconds |
| Calendar Trigger | IANA timezone, local time, and one or more weekdays; a supplied end date is inclusive |
| Document match | Exact equality on string, number, or boolean frontmatter values in the same Project; multiple conditions are ANDed; fires at most once |

A Trigger starts a fresh Session or Published Workflow. A scheduled follow-up adds a turn to an existing Session. Their interval limits and stop controls differ. Preview time schedules before creating them and check the actual next occurrences.

## When a limit error appears

First identify the destination, input, or result that exceeded its limit. File size, UTF-8 bytes, a rendered prompt, and decoded SQL output measure different things. Reduce the content or move it into referenced artifacts, then verify the operation's result.

Within these limits, permissions, supported formats, Project status, disk capacity, and provider availability can still prevent an operation. Consult [Permissions](/en/docs/permissions) and [Troubleshooting](/en/docs/troubleshooting). If an operation's outcome is unknown, establish whether the original request was accepted before submitting changed content as another request.

## Pagination is specific to the surface

| Surface | How to continue |
|---|---|
| `chat` read lists | Read `items`; when `next` is present, pass its opaque string to the same command's `--before` (`--cursor` for `chat trigger`). If `next` is absent, that command cannot read further. Check each command for count ranges and defaults ([CLI](/en/docs/cli)) |
| `aachat project read` and `aachat session read` | Pass opaque `next.before` to `--before` ([CLI](/en/docs/cli)) |
| `aachat workflow list` and `aachat workflow runs` | Pass `next_cursor` to `--before` ([CLI](/en/docs/cli)) |
| Project Database WebUI | Numbered pages with 25 / 50 / 100 rows; changing table or sort changes the query ([Database](/en/docs/database)) |
| Inbox / bounded Session decision / matched excerpts | These are bounded views, not a cursor-based full history. Use the suggested history read; Inbox does not paginate ([Sessions](/en/docs/sessions), [CLI](/en/docs/cli)) |

Do not interchange cursors, page numbers, and row limits or treat the first page as the entire result. Workflow Bundle/schema constraints are in [Workflow reference](/en/docs/workflow-reference); date and dispatch constraints are in [Triggers](/en/docs/triggers).


---

# API Connection Reference

> Choose an API entry point, call External Session Run, and understand authentication, retries, errors, and implementation boundaries.

# API Connection Reference

Use this page when connecting CI or another application to aachat, or tracing how the CLI and WebUI talk to the server. For starting new work from an external system, use **External Session Run**. For normal human and agent operations, start with the [CLI reference](/en/docs/cli). A route being present in source, or having a `/v1` prefix, does not promise a stable third-party API, a compatibility period, or a version migration policy.

## Choose the entry point and identity

| Your goal | Recommended entry point | Identity and authority |
|---|---|---|
| Start a new Session from CI or a webhook adapter | [External Session Run](/en/docs/external-session-runs); HTTP example below | A dedicated opaque bearer key fixes the project, agent, launch settings and workspace repo. It is not a human login token. |
| Manage teams, projects, members and agents; send messages; use documents, media, HTML, Project Database, Company knowledge or meetings | Human `aachat` CLI and WebUI; existing shared Client for repository development | Logged-in human identity, with team/project roles and operation-specific checks. Authentication alone does not grant write or administration rights. |
| Work inside a running Session, including messages, Asks, documents, Workflow/Trigger operations and delivery receipts | Session-provided `chat` CLI and projected contracts | Session agent identity, project coverage, current membership and lifecycle checks. A Session token is not a general-purpose service credential. |
| Start, continue or inspect interactive Sessions, Workflows and Triggers | CLI/WebUI operations and their existing Client methods | Human or Session identity according to the route; launch, ownership and project scope are checked separately. External run keys do not authorize these APIs. |
| Browse Discover agents, skills and templates, or read intentionally shared content | Public WebUI and issued share URLs | Some reads are anonymous; installing, publishing, voting or managing shares has separate authentication and ownership checks. Share tokens authorize their particular content scope. |
| Implement the WebUI, runtime or aachat infrastructure | Existing WebUI API layer, shared Client, sync and realtime implementation | Internal client/runtime protocols, one-time realtime tickets, or dedicated server/worker authority. Control/admin routes and provider webhooks are not general integration entry points. |

External Session Run starts new work; it does not expose a general API key for browsing project data, continuing any Session, approving permissions, or administering an agent. If a third-party webhook should start work, receive and validate that provider's event in your adapter, then call External Session Run. Do not send arbitrary events to aachat's provider-specific webhook endpoints.

## Prepare an external credential

Use **Start from external app** in the project's WebUI, as described in [External Session Run](/en/docs/external-session-runs). The manager must be the agent's current human owner and an active project Admin or Collaborator; the agent must also be an active project Admin or Collaborator. The project must be active and the owner's runtime must be able to start the chosen agent with the fixed launch settings and workspace repository.

The creation response contains `key`, `token`, and `run_url`. The screen presents the latter two as `AACHAT_API_KEY` and `AACHAT_API_URL`. Here, `AACHAT_API_URL` means the **complete POST URL**, ending in `/v1/external/session-runs`, not just the server origin. Use the returned URL rather than guessing a deployment hostname. Creation/rotation reveals the raw key once; listing credentials does not return it. Store it in the caller's secret store. Do not copy a human login token, Session token, GitHub token or internal worker secret into this field.

The run endpoint reads `Authorization: Bearer <key>` itself; it does not authenticate this request as a human JWT. The server stores a hash of the external key. The prompt and metadata are invocation data, so keep secrets out of both and out of logs. See [Trust Boundary](/en/docs/trust-boundary) for storage and execution boundaries.

## Send a complete request

The following shell example requires curl with `--fail-with-body`, a trusted credential URL and the key loaded into environment variables. Sending it starts real work in that credential's project. The file contains an illustrative CI event, not a live token; replace its task and event identifiers before use, then retain the exact request for retries.

```bash
# AACHAT_API_URL and AACHAT_API_KEY come from the credential creation screen.
# AACHAT_API_URL is the complete run_url, without a query string.
: "${AACHAT_API_URL:?Set the credential run_url}"
: "${AACHAT_API_KEY:?Load the key from your secret store}"

cat > external-run.json <<'JSON'
{
  "text": "Inspect the CI failure for commit abc123 and report findings in the project.",
  "idempotency_key": "ci:example/repo:12345:attempt-1",
  "metadata": {
    "source": "ci",
    "repository": "example/repo",
    "run_id": "12345"
  }
}
JSON

curl --silent --show-error --fail-with-body \
  --request POST "${AACHAT_API_URL}?wait=started" \
  --header "Authorization: Bearer ${AACHAT_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data-binary @external-run.json
```

Only `text`, `idempotency_key` and optional `metadata` are accepted in the JSON body; unknown fields are rejected. Do not add `agent_id`, `project`, `mode`, `launch` or `workspace_repo` to override the credential.

| Input | Current validation |
|---|---|
| `text` | Trimmed, nonempty, at most 100,000 UTF-8 bytes. Runtime `/loop` shortcut syntax is rejected. |
| `idempotency_key` | Trimmed, nonempty, at most 200 UTF-8 bytes; scoped to the credential ID. Use a durable external event identifier. |
| `metadata` | Optional JSON object, at most 8,192 bytes after canonical JSON serialization. Object key order is normalized; an array is not accepted. |
| `wait` query | Omitted or `accepted` returns after acceptance; `started` waits up to the current 10-second start acknowledgement timeout. No completion wait mode. |

New invocations are limited per credential to 30 in a 60-second window and 5 pending (`accepted`) invocations. These are implementation limits, not throughput guarantees. An identical retry returns the existing invocation before these new-invocation checks.

## Interpret the response and read it again

Successful POST and GET return HTTP **200** with an invocation body. The following bodies are illustrative complete shapes; IDs, timestamps and the app hostname are examples. Optional absent fields are omitted rather than necessarily emitted as `null`.

An accepted invocation can look like this, including after `wait=started` reaches its timeout:

```json
{
  "invocation_id": "11111111-1111-4111-8111-111111111111",
  "project": { "team": "example", "name": "ci-checks" },
  "agent_id": "22222222-2222-4222-8222-222222222222",
  "accepted_at": "2026-09-06T09:00:00Z",
  "status": "accepted"
}
```

Once the runtime acknowledges startup, it can look like this:

```json
{
  "invocation_id": "11111111-1111-4111-8111-111111111111",
  "project": { "team": "example", "name": "ci-checks" },
  "agent_id": "22222222-2222-4222-8222-222222222222",
  "session_id": "33333333-3333-4333-8333-333333333333",
  "accepted_at": "2026-09-06T09:00:00Z",
  "status": "started",
  "web_url": "https://app.example.test/t/example/projects/ci-checks?session=33333333-3333-4333-8333-333333333333"
}
```

`started` confirms Session startup, not task completion, CI success, code delivery or a merge. Open the returned `web_url` to follow the work. While still `accepted`, a Session may already be bound, so `session_id` and `web_url` can also be present before `started`.

Save `invocation_id`. Read that invocation without starting another Session:

```bash
INVOCATION_ID='11111111-1111-4111-8111-111111111111' # Replace with the returned ID.
curl --silent --show-error --fail-with-body \
  --header "Authorization: Bearer ${AACHAT_API_KEY}" \
  "${AACHAT_API_URL}/${INVOCATION_ID}"
```

GET returns the same response type. It is scoped to the **token used when this invocation was accepted**, not merely the credential's current token. A missing invocation or a token that does not match that acceptance returns 404. An absent or malformed bearer token returns 401.

## Retry, rotate and revoke deliberately

When a POST response is lost, resend the original request with the same `idempotency_key` and credential. If you already have `invocation_id`, GET it first. Do not generate a new event key just because of a network timeout or an `accepted` response: that can create separate work.

The request comparison includes normalized text, metadata, fixed launch and workspace context. Reusing a key with different input returns 409. JSON object key order is normalized, but changed values are different input. A terminal `failed` invocation is also returned by an identical retry; resending does not restart it. Inspect the failure and any bound Session, fix the cause, then use a new idempotency key only for an intentional new attempt.

- **Revoke or expiry:** blocks new invocations. An already accepted invocation can still be read with its acceptance token, and an identical POST retry can return it while that token still identifies the credential. Revocation is not cancellation of already accepted work or erasure of read access to it.
- **Rotate:** changes an active credential’s token. Revoked or expired credentials cannot be rotated; create a new credential. The old token no longer identifies the credential for POST, including retries. The old acceptance token can still GET invocations accepted with it; the new token cannot GET those old invocations. A same-input POST with the new token and the same idempotency key can return an existing invocation under the same credential ID.
- **Reissue:** creates a different credential identity. Idempotency does not deduplicate across credentials. Reconcile outstanding work before resubmitting through a replacement credential.

New work also rechecks the active project, the creator's current agent ownership and project membership, and the agent's active project membership. A key does not bypass changes to these relationships. Reconfigure through the authorized human owner if they no longer match. Keep acceptance tokens protected while you need them for recovery; do not publish them as diagnostic evidence.

## Errors and recovery

HTTP request rejection uses an `error` envelope, distinct from an invocation's `failure`. For example, changing `metadata` in the request to `[]` produces HTTP 400:

```json
{
  "error": {
    "code": "validation_error",
    "message": "metadata must be an object when provided."
  }
}
```

An invocation accepted earlier can later fail to start and still return HTTP 200, for example if the target project becomes inactive before startup:

```json
{
  "invocation_id": "11111111-1111-4111-8111-111111111111",
  "project": { "team": "example", "name": "ci-checks" },
  "agent_id": "22222222-2222-4222-8222-222222222222",
  "accepted_at": "2026-09-06T09:00:00Z",
  "status": "failed",
  "failure": {
    "code": "conflict",
    "message": "Target project is no longer active. Reissue the external session run key for an active project."
  }
}
```

A failed response may also contain a bound `session_id` and `web_url`. Read them before deciding to start again. Failure codes and messages depend on the actual launch failure; do not treat the example as the only failure mode.

| Observation | Next action |
|---|---|
| 400 `validation_error` | Read the message. Correct request fields, metadata, limits or `wait`; if the target agent is no longer an active Admin or Collaborator, have the human owner restore its project membership before retrying. |
| 401 `unauthorized` | Check the bearer header and intended external key, including rotation; do not replace it with a human or Session token. |
| 403 | Have the human owner check current ownership and project roles. |
| GET 404 `not_found` | Check the invocation ID and its acceptance token. Changing to the newest token does not recover an older invocation. |
| 409 `conflict` | Read the message: reconcile reused-key input, project state, launch or workspace context. A new key is appropriate only for intentional new work. |
| 410 `gone` | The credential cannot accept new work after revoke/expiry; manage it through the owner and reconcile existing invocations first. |
| 429 `rate_limited` | Back off and inspect pending work. Do not churn event keys; these limits do not promise a `Retry-After` header. |
| Network error, timeout or server error | Outcome may be unknown. GET the known invocation or resend the identical POST; retain enough event correlation to reconcile it. |
| 200 with `accepted` or `failed` | Handle `status` and `failure`, not only curl's exit status. `accepted` remains pending; `failed` requires diagnosis before a new attempt. |

## HTTP correlation IDs and redirect boundaries

On supported servers, the `X-Aachat-Request-Id` response header helps correlate an HTTP attempt. With curl, `--dump-header <file>` saves response headers separately. Obtain it through an authorized read, such as a GET for a known invocation; do not repeat a POST to obtain an ID. Replace the header destination with an actual local file and check it for secrets before sharing.

The server adopts a valid single UUID in the request header of the same name; a missing, invalid, or duplicate header produces a new UUID in the response. This is not a required authentication header and grants neither permission nor duplicate-execution protection. Use the `idempotency_key` and invocation checks above for retries. If the header or diagnostic fields cannot be obtained, leave server correlation unverified ([reading diagnostics](/en/docs/troubleshooting)).

The built-in aachat Rust API client does not follow redirects to another origin; same-origin redirects retain the existing bounded following policy. Web fetches to the aachat API reject all redirects, including same-origin ones. This restriction does not describe ordinary page navigation, external storage-grant retrieval, or users' own curl requests in general. If an API endpoint or proxy redirects, confirm the final canonical API endpoint and response with an administrator/support. Do not disable header protection as a workaround or unconditionally resend a write with an unknown outcome.

## Read the existing implementation

The source links below are optional references for developers with repository access. `kensaku63/aachat` is a private repository; viewing it requires signing in to a GitHub account with access. A 404 when opening a link anonymously does not by itself mean that the source was deleted or that the API is failing.

Reading the source is not required for an external integration. If you cannot access it, continue with [External Session Run](/en/docs/external-session-runs) for connection setup, the [CLI reference](/en/docs/cli) for normal operations, or [Troubleshooting](/en/docs/troubleshooting) to diagnose problems.

For repository development, trace an operation from its existing client method through the mounted route and request/response types to authorization and persistence. Use the source revision corresponding to the server/client you are investigating. The links below open the repository's main branch; they are reading entry points, not a separately versioned SDK specification.

| Question | Source entry point |
|---|---|
| Where are HTTP families mounted and protected? | [Server root](https://github.com/kensaku63/aachat/blob/main/crates/server/src/main.rs), [route composition](https://github.com/kensaku63/aachat/blob/main/crates/server/src/routes.rs), [authentication](https://github.com/kensaku63/aachat/blob/main/crates/server/src/auth.rs) |
| How do existing Rust callers form requests and decode errors? | [Shared Client](https://github.com/kensaku63/aachat/blob/main/crates/shared/src/client.rs) and its [operation modules](https://github.com/kensaku63/aachat/tree/main/crates/shared/src/client) |
| Which JSON fields and enum values are accepted? | [API type registry](https://github.com/kensaku63/aachat/blob/main/crates/shared/src/api_types.rs), [Session and external run types](https://github.com/kensaku63/aachat/blob/main/crates/shared/src/api_types/sessions.rs), [common error types](https://github.com/kensaku63/aachat/blob/main/crates/shared/src/api_types/common.rs) |
| Where do external run validation, retry and credential checks live? | [External run handler](https://github.com/kensaku63/aachat/blob/main/crates/server/src/routes/external_session_runs.rs), [invocation persistence](https://github.com/kensaku63/aachat/blob/main/crates/server/src/db/external_session_runs.rs), [error mapping](https://github.com/kensaku63/aachat/blob/main/crates/server/src/error.rs) |
| Where are stored constraints and changes defined? | [Database migrations](https://github.com/kensaku63/aachat/tree/main/db/migrations); read later migrations as well as the initial table definition. |

Teams/projects/membership, messages/search/timeline, shared documents/artifacts, Company/registry/meetings, Sessions/permissions/waits, Workflows/Triggers, and Discover/publication each have corresponding route and type modules. Follow the family for your use case instead of copying an unrelated HTTP literal. WebUI-specific reads and runtime writes are not interchangeable merely because they share a server.

Control/admin endpoints, development login, sync/runtime delivery, worker/gateway authorization, provider webhook payloads and realtime protocols are intentionally not presented here as callable third-party examples. Use their implementation and deployment contracts when contributing to those components. This reference adds no separate SDK, OpenAPI generator or stability guarantee.