# Reference & troubleshooting

Start with the symptom and the smallest relevant evidence. Do not expand permissions, erase state or retry uncertain effects just to make an indicator green.

## Troubleshoot by checkpoint

| Symptom | Inspect | Next action | Success evidence |
| --- | --- | --- | --- |
| soot missing from PATH | Download manifest, platform/version/digest | Obtain the right artifact or source build with access | `soot version --json` returns a version |
| Missing Pack/executable | Manifest, selected capability, dependency | Prepare dependency; do not bypass schema | Valid check and successful read tool |
| Ready but no real AI Test | Provider availability/model policy/login | Operator config/login on host | Real provider attempt evidence |
| Saved but Test disabled | Saved/active, pending activation, work_available | Activate correct revision, await acknowledgement | Test pins active revision |
| Nest cannot connect | Endpoint, TLS/origin/operator key | Exact allowed origin and correct credential type | Intended authenticated identity/scope |
| Read/write DENIED | Capability, operation binding, pool grant | Operator reviews scope, not actor label | Correct allowed read/denied write |
| Save conflict | Current revision/generation, retained draft | Reread → explicit rebase | New revision, no lost draft |
| Lost submission response | Original request/run/receipt and resource fences | GET/watch/reconcile; never replay an uncertain effect through another group | Confirmed outcome or explicit unknown |
| Automatic groups unavailable | Host `groups.auto.v1`, Soot `automatic_groups`, app/client pin | Use supported fixed/legacy mode; omitted `group_id` does not enable auto | Compatible admission, no invented grants |
| Mixed chat hidden after revocation | Grants for every contributing group | Host access review; do not copy summaries into another scope | Access to all contributors or chat remains hidden |
| Missing USD/delayed totals | Pricing coverage, closed UTC buckets, offline | Retain unknown/partial; inspect attempt detail | Unknown never converted to zero |
| Old chat fails after model change | Prior model in candidate chain | Host compatibility review; new objective/new chat | No erased or replayed durable history |

## A practical glossary

| Term | Meaning |
| --- | --- |
| Soot | One agent with explicit responsibility, mission and grants |
| Runtime host | Authority for config, providers, vault, policy, tools and durable state |
| Nest | Operator workspace, not a runtime or agent |
| Soul / mission | Stable working behavior / current responsibility and boundaries |
| Skill / tool | SOP/knowledge to read / permitted executable action |
| Pack / capability | Distribution bundle / explicitly selected skills-tools group |
| Conversation | Durable thread bound to a selected Soot/runtime and mode: auto can handle A → B → A; fixed chats and app/client pins stay fixed, legacy scope stays unchanged |
| Automatic groups | `group_id: auto` negotiated by current clients with `groups.auto.v1` and `automatic_groups: true`; native delegation chooses authorized destinations, not a required group picker |
| Group | Host-defined scope for entries, colleagues, reviewed credential-bound operations, private memory and limits; not a Nest folder or OS sandbox |
| Run | An admitted execution with ID, state and configuration revision |
| Execution | Model/tool work under host budgets and cancellation |
| Saved / active | Persisted revision / generation acknowledged in use by the host |
| Receipt | Admission/outcome evidence; pending is not completion |
| Scope / grant | Host-authorized access; data or UI labels cannot expand it |
| Data Pool | Optional shared-source service with its own policy and revisions |
| Known cost | Estimate on priced observations, not the full invoice |

For automatic collaboration, legacy API compatibility, Forge groups and public-client boundaries, read [Orchestration](https://trysoot.com/docs/orchestration/index.md).

## Maintained repository references

Use the maintained CLI/source for command and contract details when older labels or release notes differ. See the quick-start prerequisites for source-access and artifact requirements.

- [Getting started](https://github.com/2found/2agent/blob/main/docs/getting-started.md) — product path and artifact boundaries.
- [CLI](https://github.com/2found/2agent/blob/main/docs/cli.md) — spawn/check/login/run/watch/nest.
- [Configuration](https://github.com/2found/2agent/blob/main/docs/configuration.md) — host and Soot ownership.
- [Runtime Packs](https://github.com/2found/2agent/blob/main/docs/runtime-packs.md) — flat capability composition.
- [Models](https://github.com/2found/2agent/blob/main/docs/models.md) — providers/models/fallbacks.
- [Execution](https://github.com/2found/2agent/blob/main/docs/execution.md) — limits, jobs, Stop and uncertain effects.
- [Monitoring](https://github.com/2found/2agent/blob/main/docs/monitoring.md) — coverage, costs and freshness.
- [Nest browser](https://github.com/2found/2agent/blob/main/docs/nest-browser.md) — connections, identity and receipts.
- [Nest Data Pool](https://github.com/2found/2agent/blob/main/docs/nest-data-pool.md) — human CRUD and scopes.
- [Desktop Settings](https://github.com/2found/2agent/blob/main/docs/desktop-settings.md) — saved/active/Test.
- [Product integration](https://github.com/2found/2agent/blob/main/docs/product-integration.md) — backend-only credentials/identity.
- [Data Pool Pack](https://github.com/2found/soot-forge/tree/main/packs/data-pool) — dependencies and shared service setup.

## Read with a coding agent

Every chapter has clean Markdown without the site shell: append `/index.md`, or use the `.md` alias. The [Markdown index](/docs/index.md) links all chapters; [locale discovery](/docs/llms.txt) helps find the right source. Unknown Markdown paths return a real 404, not an app shell.