Goal-driven capability planning + local-first knowledge model (read-only guides + agent-authored supplements)

[jaylfc]

Vision (Jay 2026-06-14)

A user tells the taOS agent a GOAL ("I want to make a children's storybook", "transcribe these meetings", "build a RAG over my docs"). The agent looks at what the cluster can actually do, and if software needs installing / updating / replacing to get the BEST result, it says so and offers to do it. Extends #31 (agent knowledge of available frameworks/backends).

The planning loop

1. Read available capabilities + what's installed/live (cluster/capabilities.py + the catalog), and the hardware tiers.
2. Compare against what the goal needs for a good result.
3. Recommend: use X as-is / install Y / update Z / replace W with a better current option. One-click apply via the store/installers, with the same easy guided flow.
4. Verify it actually works (detect != work), then proceed.

Local-first knowledge (cannot rely on web search)

The agent must NOT depend on reliable web access. Knowledge ships locally and is kept fresh:

• Read-only canonical guides = the source of truth (the agent-manual / canonical-skills pattern we already PROVED: open-app-first guides got 4B local models driving the OS). Read-only so they can't be corrupted or drift per-agent. Relates to the canonical-skills idea (Canonical taOS-operations skills: one source of truth, framework-portable injection, permission-bound #595).
• A regularly-refreshed, checked-in catalog of the latest models / tools / frameworks (the upstream-tracking idea Upstream dependency tracking: inventory + release/changelog monitoring + feature-awareness digest #596): which model/tool is currently best for a capability on which hardware tier, with install info. WE refresh it (research cadence); the agent reads it instead of searching the web. This is what lets the agent recommend "replace W with the current best" without live search.
• The model's own capability/age is unknown and untrusted, so the guides carry the knowledge, not the model.

Agent-authored supplementary guides (new)

The read-only canonical guides cannot be edited by the agent, BUT the agent can CREATE supplementary, persistent guides:

• Personal (this agent's own learnings / improvements -- e.g. "for this user's 3060, FLUX Q3 fits, Q4 OOMs") -- an agent-specific knowledge layer that persists across runs.
• Shareable (publish to the community like apps/themes/packages) so good supplements spread.
• Layered over (never overwriting) the canonical guides at read time. Likely a strong fit for agent-specific tuning.

Build on / relate to

• Backend-driven discovery — /api/models live catalog join #31 (agent offers to install/use frameworks/backends) -- this is its full form.
• The agent-manual (docs/agent-manual/, read-only, compiled) + skills.py -- the proven read-only-guide pattern.
• The store/installers (the apply path) + describe_*_capabilities tools (the read path).
• canonical-skills (Canonical taOS-operations skills: one source of truth, framework-portable injection, permission-bound #595) and upstream-tracking (Upstream dependency tracking: inventory + release/changelog monitoring + feature-awareness digest #596) concepts.
• Cluster app: capability map + live placement + move things across nodes + agent-assisted auto-organise #897 (cluster app shows the capabilities this plans against); Universal control plane: live queue + full-trace observability/audit that every interaction flows through #896 (control plane shows the runs).

Notes

Guides extremely easy to follow (proven bar). Brainstorm -> spec with @taOSmd where the memory/agent side overlaps. Do not block the storybook demo.