07 / Reference
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.
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 — product path and artifact boundaries.
- CLI — spawn/check/login/run/watch/nest.
- Configuration — host and Soot ownership.
- Runtime Packs — flat capability composition.
- Models — providers/models/fallbacks.
- Execution — limits, jobs, Stop and uncertain effects.
- Monitoring — coverage, costs and freshness.
- Nest browser — connections, identity and receipts.
- Nest Data Pool — human CRUD and scopes.
- Desktop Settings — saved/active/Test.
- Product integration — backend-only credentials/identity.
- Data Pool Pack — 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 links all chapters; locale discovery helps find the right source. Unknown Markdown paths return a real 404, not an app shell.
Content reviewed: 2026-10-09