facult 2.11.0 → 2.13.0

package/assets/packs/facult-operating-model/AGENTS.global.md

@@ -5,6 +5,7 @@ This machine has a default Facult operating-model layer available.
 When work produces durable friction, weak verification, stale guidance, or a missing skill/tool capability, preserve that signal with `fclt ai writeback ...` when the target and scope are clear. When repeated writebacks or clearly missing capability point at a concrete improvement, use `fclt ai evolve ...` or the `capability-evolution` skill to make a reviewable proposal.
 
 For work-unit framing, read `@builtin/facult-operating-model/instructions/WORK_UNITS.md`.
+For composing refs, snippets, instructions, skills, agents, MCP, and automations as evolvable units, read `@builtin/facult-operating-model/instructions/CAPABILITY_COMPOSITION.md`.
 For writeback and evolution, read `@builtin/facult-operating-model/instructions/EVOLUTION.md`.
 For learning and writeback defaults, read `@builtin/facult-operating-model/instructions/LEARNING_AND_WRITEBACK.md`.
 For deciding whether capability belongs in global or project scope, read `@builtin/facult-operating-model/instructions/PROJECT_CAPABILITY.md`.

package/assets/packs/facult-operating-model/instructions/CAPABILITY_COMPOSITION.md

@@ -0,0 +1,76 @@
+---
+description: "Compose small capability units across global and project roots, then evolve the smallest affected unit."
+tags: ["facult", "composition", "refs", "snippets", "instructions"]
+---
+
+# Capability Composition
+
+Use `fclt` capability as small units that can be composed, inspected, rendered, and evolved independently.
+
+The main units are:
+
+- instructions: standalone markdown doctrine such as language preferences, verification rules, or review standards
+- snippets: small markdown partials inserted into one or more rendered docs
+- skills: task-specific workflows with `SKILL.md`
+- agents: focused role manifests
+- MCP definitions: tool interfaces and their safe auth shape
+- automations: scheduled review or maintenance loops
+- tool rules/config: tool-specific defaults and policy
+
+## Composition Rules
+
+- Keep reusable doctrine in `instructions/`.
+- Keep repeated paragraphs or policy blocks in `snippets/`.
+- Keep workflow execution in `skills/`.
+- Keep persona or delegation behavior in `agents/`.
+- Keep tool wiring in `mcp/` and `tools/<tool>/`.
+- Compose broad agent docs from refs and snippets instead of copying text by hand.
+- Prefer one narrow reusable unit over one large instruction file that mixes unrelated domains.
+
+Examples:
+
+- `@ai/instructions/BUN.md` for shared Bun preferences.
+- `@ai/instructions/RUST.md` for shared Rust preferences.
+- `@project/instructions/TESTING.md` for repo-specific test policy.
+- `<!-- fclty:global/codex/baseline -->` for a shared rendered block.
+
+## Scope
+
+Use global scope for capability that should follow the user across projects.
+
+Use project scope for capability that belongs to a repo, team workflow, architecture, or local test harness.
+
+Promote project capability to global only when repeated evidence shows reuse across projects. Do not globalize a project quirk just because it worked once.
+
+## Writeback and Evolution
+
+Target the smallest affected unit.
+
+- If a paragraph is reused in several rendered docs, target the snippet.
+- If a domain rule is wrong, target the instruction.
+- If a workflow is incomplete, target the skill.
+- If a delegated role is unclear, target the agent.
+- If a tool interface is missing or unsafe, target the MCP or tool config.
+- If a scheduled review loop is noisy or missing context, target the automation.
+
+Good writeback targets are graph-backed selectors when possible:
+
+```bash
+fclt ai writeback add --kind missing_context --summary "Bun guidance did not cover test runner selection." --asset instruction:BUN
+fclt ai writeback add --kind reusable_pattern --summary "Project test policy should become a shared verification snippet." --asset @project/instructions/TESTING.md
+fclt ai writeback add --kind bad_default --summary "The review automation escalated one-off preferences." --asset automation:evolution-review
+```
+
+Use `fclt ai evolve ...` only after repeated signal, a clearly missing capability, or a stale canonical asset points at a concrete change. Prefer the smallest valid proposal kind: `update_asset`, `create_asset`, `extract_snippet`, `add_skill`, or `promote_asset`.
+
+## Agent Defaults
+
+When an agent sees a repeated preference like "use Bun for JS projects" or "prefer Cargo nextest for Rust tests", it should not bury that in chat. It should identify whether the durable unit is:
+
+- a global instruction
+- a project instruction
+- a snippet reused by rendered docs
+- a skill workflow
+- a project-to-global promotion candidate
+
+Then it should record writeback against that unit, or draft a proposal when the evidence is already strong enough.

package/assets/packs/facult-operating-model/instructions/EVOLUTION.md

@@ -9,6 +9,8 @@ Use writeback and evolution to improve the AI operating layer itself.
 
 Evolution is the synthesis and change side of the feedback loop. It turns accumulated writebacks, repeated tool friction, stale canonical assets, or clearly missing capability into small reviewable changes to instructions, skills, snippets, agents, or other markdown canonical assets.
 
+Use capability composition when choosing the target. Instructions, snippets, skills, agents, MCP/tool config, and automations are separate units. Target the smallest unit that actually needs to change instead of rewriting a broad agent doc.
+
 ## When To Record Writeback
 
 Record writeback when one of these is true:
@@ -60,6 +62,14 @@ Every good writeback should try to include:
 - the right scope
 - domain or tags when useful
 
+Good target examples:
+
+- `instruction:BUN` when shared Bun guidance is stale or missing
+- `@project/instructions/TESTING.md` when repo test policy needs project-scoped evolution
+- `snippet:global/lang/bun` when a repeated rendered block should be fixed or extracted
+- `skill:capability-evolution` when a workflow skill is missing steps or examples
+- `automation:evolution-review` when the scheduled review loop is noisy or incomplete
+
 ## Operator Flow
 
 Typical workflow:
@@ -88,7 +98,7 @@ Review surfaces:
 
 Evolution proposal metadata, markdown drafts, patch artifacts, writeback queues,
 and journals are runtime state. `fclt` stores JSON queues, proposal records,
-draft refs, patches, and journals in machine-local Facult state. It mirrors
+draft refs, patches, and journals in machine-local `fclt` state. It mirrors
 human-readable review artifacts into global `~/.ai/writebacks/...` and
 `~/.ai/evolution/...`, including project-scoped artifacts under
 `projects/<slug-hash>/` with cwd/project metadata in frontmatter. Canonical
@@ -122,6 +132,14 @@ Current supported proposal kinds:
 
 Use the smallest durable change that fits the evidence.
 
+Examples:
+
+- `update_asset`: fix a stale instruction, snippet, agent, or automation markdown asset.
+- `create_asset`: add a missing instruction such as `BUN.md` or `RUST.md`.
+- `extract_snippet`: move repeated guidance out of several docs into one snippet.
+- `add_skill`: create a workflow when instructions are not enough.
+- `promote_asset`: move a proven project instruction/snippet/skill toward global reuse.
+
 ## Review And Apply Rules
 
 - draft before apply

package/assets/packs/facult-operating-model/instructions/LEARNING_AND_WRITEBACK.md

@@ -29,7 +29,7 @@ fclt ai writeback add --kind <kind> --summary "<summary>" --asset <asset-selecto
 ```
 
 The writeback queue is runtime state, not canonical source. `fclt` stores JSON
-queue state in machine-local Facult state so sandboxed agents can record durable
+queue state in machine-local `fclt` state so sandboxed agents can record durable
 friction without mutating canonical assets unless an evolution proposal is later
 reviewed and applied.
 
@@ -45,6 +45,15 @@ Project-scoped writebacks should usually be recorded from the repo that produced
 the evidence. Global writebacks should be reserved for shared doctrine, shared
 skills, shared agents, tool behavior, or cross-project capability gaps.
 
+Target the smallest composable unit that explains the friction:
+
+- instruction: domain guidance, preferences, verification rules, or review doctrine
+- snippet: repeated markdown block used by more than one rendered doc
+- skill: workflow execution steps or examples
+- agent: delegated role behavior
+- MCP/tool config: tool interface, auth shape, or rendered integration
+- automation: scheduled review loop, cadence, prompt, or memory
+
 ## Record Writeback When
 
 - the same failure or weak loop appears again
@@ -54,6 +63,7 @@ skills, shared agents, tool behavior, or cross-project capability gaps.
 - a cross-project behavior probably belongs in global capability
 - a skill, tool, MCP, plugin, automation, or instruction gap repeatedly slows work down
 - an agent has to restate the same workaround, verification rule, or review rule
+- a repeated preference should become an atomic instruction such as `BUN.md`, `RUST.md`, or a project-specific testing policy
 
 ## Do Not Record Writeback For
 

package/docs/README.md

@@ -1,18 +1,29 @@
 # fclt Documentation
 
-These docs explain the product model behind `fclt`. The root [README](../README.md) is the quick start and command reference. The files here explain why the pieces exist and how they fit together.
+These docs explain how `fclt` stores, inspects, composes, renders, and improves AI capability.
 
-Start here:
+Start with the root [README](../README.md) for installation and first workflows. Use these guides when you need the model, safety rules, or command details.
+
+The concepts guide includes the [feedback-loop diagram](./assets/fclt-capability-loop.png) that explains why `fclt` exists: setup once, let agents preserve friction, then review the changes that should improve future work.
+
+## Guides
 
 - [Concepts](./concepts.md): canonical roots, generated state, rendered outputs, scopes, and asset types.
-- [Managed Mode](./managed-mode.md): when to let `fclt` write tool files, and how adoption works.
+- [Composable Capability](./composable-capability.md): refs, snippets, instruction templates, and evolvable units.
 - [Project `.ai`](./project-ai.md): how repo-local capability works without leaking project review state into the repo.
-- [Built-In Pack](./built-in-pack.md): the packaged operating-model layer for writeback and evolution.
-- [Writeback And Evolution](./writeback-evolution.md): how real-work friction becomes reviewable capability changes.
-- [Roadmap](./roadmap.md): current product gaps and non-goals.
+- [Built-in pack](./built-in-pack.md): the packaged operating-model layer for writeback and evolution.
+- [Writeback and evolution](./writeback-evolution.md): how real-work friction becomes reviewable capability changes.
+- [Managed mode](./managed-mode.md): when to let `fclt` write tool files, and how adoption works.
+- [Security and trust](./security-trust.md): source trust, audit, secrets, and commit hygiene.
+- [Automations](./automations.md): recurring Codex loops for learning review, evolution review, and tool-call audit.
+- [Command reference](./reference.md): command groups and common flags.
+- [Roadmap](./roadmap.md): current product gaps and planned work.
 
-## Documentation Policy
+## Reading Order
 
-Public docs should use generic examples. Do not include personal account names, private customer names, local machine paths, secret values, or project-specific operating notes. Use placeholders such as `/path/to/repo`, `example.com`, and `~/.ai`.
+New users should read:
 
-Machine-local state and review artifacts can contain project metadata. `fclt` keeps those artifacts in machine-local Facult state and global `~/.ai/writebacks` / `~/.ai/evolution` review directories, not in repo-local project `.ai` directories.
+- [Concepts](./concepts.md)
+- [Project `.ai`](./project-ai.md) if working in a repo
+- [Managed mode](./managed-mode.md) only before allowing `fclt` to write tool files
+- [Writeback and evolution](./writeback-evolution.md) before setting up feedback loops

package/docs/automations.md

@@ -0,0 +1,68 @@
+# Automations
+
+`fclt` can scaffold Codex automations that run the feedback loop on a schedule.
+
+Use automations for review and synthesis, not for bypassing review. They should preserve useful signal, group repeated patterns, and draft proposals only when the target is concrete.
+
+## Templates
+
+Learning review:
+
+```bash
+fclt templates init automation learning-review \
+  --scope project \
+  --project-root /path/to/repo \
+  --status PAUSED
+```
+
+Evolution review:
+
+```bash
+fclt templates init automation evolution-review \
+  --scope wide \
+  --cwds /path/to/repo-a,/path/to/repo-b \
+  --status PAUSED
+```
+
+Tool-call audit:
+
+```bash
+fclt templates init automation tool-call-audit \
+  --scope project \
+  --project-root /path/to/repo \
+  --status PAUSED
+```
+
+## Scopes
+
+- `project`: one repo. Use this for repo-specific writeback, verification, and tool friction.
+- `wide`: a small related set of repos. Use this for shared capability review.
+- `global`: global capability and shared agent behavior.
+
+Keep wide scopes intentionally small. A good automation should preserve source boundaries instead of mixing unrelated repos into one vague proposal.
+
+## Output
+
+Automation files are written to:
+
+```text
+~/.codex/automations/<name>/automation.toml
+~/.codex/automations/<name>/memory.md
+```
+
+When Codex is managed by `fclt`, canonical automation sources can live under:
+
+```text
+~/.ai/automations/<name>/
+<repo>/.ai/automations/<name>/
+```
+
+Project-scoped automation sources are default-deny for managed sync. Add their names to `[project_sync.codex].automations` before project managed sync can render them into the shared live Codex automation store.
+
+## Suggested Cadence
+
+- daily or per-project `learning-review` for durable signal
+- weekly `evolution-review` for proposal triage
+- targeted `tool-call-audit` when tool failures, missing skills, or shallow-success patterns repeat
+
+High-risk global changes should still move through proposal review before apply.

package/docs/built-in-pack.md

@@ -1,4 +1,4 @@
-# Built-In Pack
+# Built-in Pack
 
 `fclt` ships an operating-model pack:
 
@@ -6,13 +6,14 @@
 assets/packs/facult-operating-model/
 ```
 
-It provides a default feedback loop for agents that use `fclt`.
+It provides default guidance for agents that use `fclt`: define the work, verify it, record durable feedback, and turn repeated signal into reviewed changes.
 
 ## Included Assets
 
 Instructions:
 
 - `WORK_UNITS.md`
+- `CAPABILITY_COMPOSITION.md`
 - `LEARNING_AND_WRITEBACK.md`
 - `EVOLUTION.md`
 - `PROJECT_CAPABILITY.md`
@@ -79,13 +80,20 @@ sync_defaults = false
 
 ## Design Rule
 
-The built-in pack should stay small. It should teach:
+The built-in pack should stay small. It teaches:
 
 - work-unit discipline
+- composable refs, snippets, instructions, skills, agents, MCP, and automations
 - verification
 - writeback
 - evolution proposal review
 - project/global scope decisions
 - managed-mode ownership boundaries
 
-It should not become a pile of preferences. Put project-specific behavior in project `.ai`; promote to global only when repeated evidence proves reuse.
+Keep project-specific behavior in project `.ai`. Promote it only when repeated evidence shows it is reusable outside that project.
+
+## Next
+
+- Read [Composable Capability](./composable-capability.md) for refs, snippets, and instruction templates.
+- Read [Writeback and evolution](./writeback-evolution.md) for the feedback loop.
+- Read [Managed mode](./managed-mode.md) before rendering the pack into a tool home.

package/docs/composable-capability.md

@@ -0,0 +1,178 @@
+# Composable Capability
+
+`fclt` treats AI behavior as small capability units that can be composed into larger agent instructions and evolved independently.
+
+This prevents one giant agent file from becoming the only place to put every preference, workflow, and exception. A language preference can live in one instruction. A repeated rendered block can live in one snippet. A workflow can live in one skill. Each unit can receive targeted writeback and targeted evolution.
+
+This is the core model:
+
+- write domain guidance once
+- compose it with refs and snippets
+- render it only where a tool should receive it
+- target writeback at the smallest unit that needs to change
+
+## Units
+
+Use `instructions/` for reusable markdown doctrine.
+
+Examples:
+
+```text
+~/.ai/instructions/BUN.md
+~/.ai/instructions/RUST.md
+<repo>/.ai/instructions/TESTING.md
+```
+
+Use `snippets/` for partial blocks inserted into rendered docs.
+
+Examples:
+
+```text
+~/.ai/snippets/global/codex/baseline.md
+~/.ai/snippets/global/lang/bun.md
+<repo>/.ai/snippets/global/project/testing.md
+```
+
+Use `skills/` for executable workflows, `agents/` for delegated roles, `mcp/` for tool interfaces, and `automations/` for scheduled loops.
+
+## Refs
+
+Canonical refs let a markdown asset point at another asset without hard-coding machine paths:
+
+```text
+@ai/instructions/BUN.md
+@project/instructions/TESTING.md
+@builtin/facult-operating-model/instructions/WORK_UNITS.md
+```
+
+Use global refs for reusable user-owned capability. Use project refs for repo-owned capability. Use built-in refs for packaged defaults.
+
+Config-backed refs are useful when the concrete path should be named in `config.toml`:
+
+```toml
+version = 1
+
+[refs]
+language_defaults = "@ai/instructions/BUN.md"
+project_testing = "@project/instructions/TESTING.md"
+```
+
+Rendered markdown can use those refs through the render context when a tool adapter supports that target.
+
+## Snippets
+
+Snippets use paired HTML markers:
+
+```md
+<!-- fclty:global/lang/bun -->
+<!-- /fclty:global/lang/bun -->
+```
+
+The marker above resolves to:
+
+```text
+snippets/global/lang/bun.md
+```
+
+Create and inspect snippets with:
+
+```bash
+fclt templates init snippet global/lang/bun
+fclt snippets list
+fclt snippets show global/lang/bun
+fclt snippets sync --dry-run AGENTS.global.md
+```
+
+Use snippets when the same block appears in more than one rendered doc, or when a stable block should be independently targetable by writeback and evolution.
+
+## Instruction Templates
+
+Create a new instruction scaffold with:
+
+```bash
+fclt templates init instruction BUN
+fclt templates init instruction lang/RUST
+```
+
+That writes:
+
+```text
+instructions/BUN.md
+instructions/lang/RUST.md
+```
+
+An instruction can include refs, snippet markers, examples, and writeback targeting guidance. Keep one instruction focused on one reusable domain. For example:
+
+- `BUN.md`: JavaScript runtime/package/test preferences.
+- `RUST.md`: Rust formatting, linting, and test preferences.
+- `WRITING.md`: voice and editorial rules.
+- `VERIFICATION.md`: proof standards.
+
+## Composition Pattern
+
+A global `AGENTS.global.md` can stay short and compose units:
+
+```md
+# Global Agent Instructions
+
+For work-unit framing, read `@ai/instructions/WORK_UNITS.md`.
+For JS/Bun projects, read `@ai/instructions/BUN.md`.
+For Rust projects, read `@ai/instructions/RUST.md`.
+
+<!-- fclty:global/codex/baseline -->
+<!-- /fclty:global/codex/baseline -->
+```
+
+A project can add narrower guidance:
+
+```md
+# Project Agent Instructions
+
+For project test policy, read `@project/instructions/TESTING.md`.
+For local deployment rules, read `@project/instructions/DEPLOYMENT.md`.
+```
+
+This keeps global defaults reusable and lets projects override or extend them without rewriting the whole global file.
+
+## Evolution
+
+Target the smallest unit that actually needs to change:
+
+- bad or stale domain guidance: update the instruction
+- repeated block copied in several docs: extract a snippet
+- missing workflow: add or update a skill
+- unclear delegation behavior: update an agent
+- tool integration gap: update MCP/tool config or create a tooling task
+- project-local pattern that proved reusable: promote the asset
+
+Examples:
+
+```bash
+fclt ai writeback add --kind missing_context --summary "Bun guidance did not cover test runner selection." --asset instruction:BUN
+fclt ai writeback add --kind reusable_pattern --summary "Project testing policy should become a shared verification snippet." --asset @project/instructions/TESTING.md
+fclt ai evolve propose
+```
+
+Do not create a global proposal for one-off taste. Use writeback to preserve evidence, then evolve when the signal repeats or the missing capability is already clear.
+
+## Review
+
+Use these surfaces:
+
+```bash
+fclt list instructions --global
+fclt list snippets --global
+fclt show instruction:BUN
+fclt graph deps AGENTS.global.md
+fclt graph dependents @ai/instructions/BUN.md
+fclt ai writeback group --by asset
+fclt ai evolve list
+```
+
+Open `~/.ai/writebacks/` and `~/.ai/evolution/` in a markdown editor to inspect review artifacts with frontmatter status, scope, targets, project metadata, evidence, and proposal state.
+
+## Next
+
+- Read [Writeback and evolution](./writeback-evolution.md) for proposal flow.
+- Read [Built-in Pack](./built-in-pack.md) for packaged defaults.
+- Use [Command reference](./reference.md) for template and graph commands.

package/docs/concepts.md

@@ -4,6 +4,10 @@
 
 The important distinction is ownership. A file can be source, generated state, machine runtime state, a rendered output, or a review artifact. Treating those as separate layers prevents sync surprises.
 
+![fclt capability loop: setup, capability, agents, work units, writebacks, evolution, approval, and better future agents](./assets/fclt-capability-loop.png)
+
+The intended operating model is agent-led after setup. Users install and approve broad changes; agents inspect capability, run work units, record durable friction, and use repeated signal to propose small improvements.
+
 ## Roots And Scopes
 
 Global root:
@@ -66,7 +70,7 @@ Examples:
 ~/.ai/.facult/ai/graph.json
 ```
 
-Project generated state lives in machine-local Facult state, not in the repo.
+Project generated state lives in machine-local `fclt` state, not in the repo.
 
 Machine runtime state records local behavior and history.
 
@@ -111,6 +115,8 @@ Common canonical asset types:
 
 Not every asset must be rendered into every tool. Use inventory and policy first, then managed sync only where `fclt` should own the rendered output.
 
+For concrete composition patterns, see [Composable Capability](./composable-capability.md).
+
 ## Feedback Loop
 
 The durable loop is:
@@ -121,3 +127,9 @@ The durable loop is:
 4. Draft the smallest valid proposal.
 5. Review and apply accepted changes to canonical source.
 6. Re-index and sync only the surfaces that should receive the change.
+
+## Next
+
+- Read [Project `.ai`](./project-ai.md) before adding repo-local capability.
+- Read [Managed mode](./managed-mode.md) before allowing `fclt` to write tool files.
+- Read [Composable Capability](./composable-capability.md) to split guidance into instructions, snippets, skills, agents, MCP, and automations.

package/docs/managed-mode.md

@@ -1,4 +1,4 @@
-# Managed Mode
+# Managed mode
 
 Managed mode is optional. Use it when you want `fclt` to write rendered files into a tool home. Do not use it just to inspect or normalize existing tool-native state.
 
@@ -37,9 +37,9 @@ When live content differs from canonical content:
 - rendered docs/config with local edits are skipped unless an explicit conflict option allows overwrite
 - built-in rendered defaults require `--builtin-conflicts overwrite` before replacing local edits
 
-This is deliberate. Managed mode should be boring and reversible.
+This is deliberate. Managed mode should be predictable and reversible.
 
-## Project Managed Mode
+## Project managed mode
 
 Project sync is default-deny. A project `.ai` root can exist without rendering anything into repo-local tool outputs.
 
@@ -60,7 +60,7 @@ tool_config = true
 
 If a repo-local `.ai` contains only generated state and no canonical assets, `fclt status --project` reports a generated-only warning and `fclt sync --project` skips. Initialize or restore canonical source before syncing managed project output.
 
-## When Not To Use Managed Mode
+## When not to use managed mode
 
 Do not use managed mode when:
 
@@ -71,3 +71,9 @@ Do not use managed mode when:
 - you are debugging and need read-only evidence first
 
 Use `fclt inventory`, `scan`, `list`, `show`, `graph`, `status`, and `audit` instead.
+
+## Next
+
+- Read [Project `.ai`](./project-ai.md) for repo-local sync policy.
+- Read [Security and trust](./security-trust.md) for MCP secrets and audit.
+- Use [Command reference](./reference.md) for common managed-mode commands.

package/docs/project-ai.md

@@ -1,6 +1,6 @@
 # Project `.ai`
 
-A project `.ai` root stores repo-owned capability. It is not a dumping ground for generated state, review queues, or private local context.
+A project `.ai` root stores repo-owned capability. It is for source that should travel with the codebase, not for generated state, review queues, or private local context.
 
 Create one with:
 
@@ -44,11 +44,11 @@ Do not put these in project `.ai`:
 - secrets
 - private review artifacts
 
-Project-scoped writebacks and evolution proposals are stored in machine-local Facult state and mirrored for review under global `~/.ai/writebacks/projects/<slug-hash>/` and `~/.ai/evolution/projects/<slug-hash>/`.
+Project-scoped writebacks and evolution proposals are stored in machine-local `fclt` state and mirrored for review under global `~/.ai/writebacks/projects/<slug-hash>/` and `~/.ai/evolution/projects/<slug-hash>/`.
 
-## Generated-Only Roots
+## Migration From Generated-Only Roots
 
-Older versions could leave `<repo>/.ai/.facult/ai/index.json` and `graph.json` behind without any canonical source. That makes the repo look like it has project AI state even though there is nothing durable to render.
+Some repos may contain `<repo>/.ai/.facult/ai/index.json` and `graph.json` without any canonical source. That makes the repo look like it has project AI state even though there is nothing durable to render.
 
 Current behavior:
 
@@ -79,6 +79,12 @@ tool_config = true
 
 This includes inherited global assets. If a global skill should appear in project-managed Codex output, list it explicitly.
 
+## Next
+
+- Read [Concepts](./concepts.md) for source, generated state, machine-local state, and rendered outputs.
+- Read [Managed mode](./managed-mode.md) before syncing project assets into tool outputs.
+- Read [Security and trust](./security-trust.md) before committing MCP config.
+
 ## Verification
 
 Use these commands after changing project `.ai`: