# AI context for dblurt

This directory is a thin AI-specific context layer for assistants that generate, review or modify `@beblurt/dblurt` code.

It is not a second manual. Human explanations remain canonical in `guide/`. Reusable code remains canonical in `examples/`.

## Directory name decision

The directory is currently named `ai/` because it is short, discoverable, neutral across tools, and matches the user-facing purpose: AI assistant context. Alternatives were considered:

| Name | Advantage | Drawback |
| --- | --- | --- |
| `context/` | generic, broad | ambiguous; could mean runtime context or project context |
| `assistant/` | human-readable | less common; sounds like one tool/persona |
| `knowledge/` | durable framing | vague; may attract duplicated guide content |
| `skills/` | close to agent ecosystems | conflicts with generated `SKILL.md` concepts and Hermes-style skills |
| `ai/` | concise, discoverable, tool-neutral | slightly broad; requires rules to prevent becoming a second guide |

Recommendation: keep `ai/` for now. Reconsider only if a future tool requires a specific directory convention.

## Start here

| Need | Canonical source |
| --- | --- |
| Package overview | `../README.md` |
| First human learning path | `../guide/getting-started.md` |
| Domain vocabulary | `../guide/BLOCKCHAIN_MODEL.md` |
| API surface routing | `../guide/api-guide.md` |
| Layer 1 / Nexus details | `../guide/nexus.md` |
| Code generation constraints | `./coding-rules.md` |
| Common mistakes | `./pitfalls.md` |
| Security constraints | `./security-constraints.md` |
| Repository workflow | `../AGENTS.md` and `../guide/maintainer-workflows.md` |
| Reusable examples | `../examples/README.md` |

## Operational rules

- Identify the layer before selecting a helper: Blurt Layer 1, Nexus Layer 2 or local utility.
- Prefer existing examples over invented snippets.
- Keep human explanations in `../guide/`, executable examples in `../examples/`, and AI-only constraints in `../ai/`.
- Run `npm run docs:check` after documentation, example or AI-context changes when practical.
- If behavior is not proven by docs, source, tests or live validation, label it as unverified.

## AI context rules

- Link to canonical docs; do not copy them.
- Prefer `examples/` over invented snippets.
- Treat `guide/BLOCKCHAIN_MODEL.md` as the semantic vocabulary source.
- Generated views such as `llms.txt`, `llms-core.txt` and `llms-full.txt` do not exist yet.
- Do not edit generated directories such as `docs/`, `lib/`, `dist/` or `coverage/`.