docs: formalize documentation and normative language rules

.agents/skills/docs/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: docs
+description: Create, edit, and review any Markdown doc in this repo against the conventions in /docs/BUILDING.md and /docs/SPEC_CONVENTIONS.md. Use whenever a Markdown doc is created, edited, or reviewed anywhere in the repo.
+user-invocable: true
+---
+
+> [!IMPORTANT]
+> The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT,
+> RECOMMENDED, MAY, and OPTIONAL follow RFC 2119 and RFC 8174.
+>
+> This document MUST use these terms, in uppercase, when expressing normative
+> requirements, permissions, recommendations, or prohibitions. It MUST NOT use
+> alternative words or lowercase variants as normative keywords.
+
+## Sources of truth
+
+- [`docs/BUILDING.md`](../../../docs/BUILDING.md) — repo-wide documentation conventions.
+- [`docs/SPEC_CONVENTIONS.md`](../../../docs/SPEC_CONVENTIONS.md) — additional conventions for
+  feature docs and their illustrative examples.
+
+Before any create, edit, or review, you MUST read the applicable sources in full:
+the repo-wide baseline always applies; the feature-doc conventions also apply
+to a module's `README.md`, its `docs/`, and the illustrative example set.
+You MUST apply every relevant rule and template directly from those sources.
+You MUST NOT rely on memory or duplicate their conventions in this skill.
+
+## On create
+
+You MUST make the new document conform to the applicable conventions.
+
+## On edit
+
+You MUST keep the document conforming after the change. You MUST NOT introduce
+changes that violate the applicable conventions.
+
+## On review
+
+You MUST check the requested documents against the applicable conventions.
+For a module review, you MUST include its `README.md` and `docs/`; if no module
+is specified, you MUST review the illustrative example set.
+
+You MUST inventory the Markdown files within the review scope and check that
+every document is reachable by following documentation links from the relevant
+entry point. You MAY use file search to build the inventory and content search
+to verify links or patterns. These searches MUST NOT replace following the
+documentation links to read and understand the documents.
+
+You MUST verify every relative link's target and any referenced identifier
+anchor. You MUST report contradictions within a source as separate findings.
+
+You MUST NOT edit files or redesign conventions during review. Gaps in the
+conventions MUST be reported as observations, separately from conformance
+findings. You MUST respect the documented exception for the illustrative
+example set's location under root `docs/`.
+
+## Review output
+
+You MUST provide a short list of findings, each with the file, line if
+applicable, issue, and the source rule that defines the expected behavior.
+If everything conforms, you MUST state that plainly. You MUST NOT invent
+findings.

.gitignore

@@ -77,7 +77,6 @@
 
 !/README.md
 !/AGENTS.md
-!/BUILDING.md
 !/LICENSE
 
 !/.agents

AGENTS.md

@@ -1,10 +1,35 @@
 ---
 title: AGENTS
-summary: Entry point for agent instructions and the repository conventions they must follow.
+summary: Entry point for agent instructions and the repository conventions they MUST follow.
 tags: [agents, instructions, repository, coding-conventions]
 ---
 
-See [BUILDING.md](./BUILDING.md) for coding rules and conventions.
+> [!IMPORTANT]
+> The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT,
+> RECOMMENDED, MAY, and OPTIONAL follow RFC 2119 and RFC 8174.
+>
+> This document MUST use these terms, in uppercase, when expressing normative
+> requirements, permissions, recommendations, or prohibitions. It MUST NOT use
+> alternative words or lowercase variants as normative keywords.
 
-Agent skills live in [.agents/skills/](./.agents/skills/). Each skill's
-`SKILL.md` front-matter describes when to use it.
+When learning about Kraf or looking for documentation, agents MUST start here
+and follow the documentation links to documents relevant to the task. Agents
+MUST NOT use content search (such as grep or ripgrep) as a substitute for
+following those links.
+
+## Docs
+
+- [README.md](./README.md) — what Kraf is.
+- [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) — cross-domain architecture (system
+  context, modules, ports and adapters, dependency rule).
+- [docs/BUILDING.md](./docs/BUILDING.md) — repo conventions (organization, build, test,
+  CI, naming, docs front-matter).
+- [docs/CODE_STANDARDS.md](./docs/CODE_STANDARDS.md) — non-negotiable code invariants
+  (amend, never break).
+- [docs/SPEC_CONVENTIONS.md](./docs/SPEC_CONVENTIONS.md) — documentation & spec conventions (intent,
+  specification, acceptance, ADR).
+
+## Skills
+
+- [.agents/skills/](./.agents/skills/) — each skill's `SKILL.md` front-matter
+  says when to use it.

README.md

@@ -16,12 +16,25 @@ doesn't.
 
 Kraf's guiding rule: **materialize only what the workload proves it needs.**
 
-The project is currently under active development. Its first working slice is
-environment variable resolution and isolation — an isolated `HOME` and working
-directory per run, real system state passed through deliberately rather than by
-accident — materialized into a shell you can use today.
+## Vision
 
-## Contributing
+Kraf's larger aim is to expose a project as a headless IDE runtime for agents:
+not an editor, and not a closed platform, but a layer beneath or beside them.
+Optionally paired with isolated environments, it will surface a project's files,
+diagnostics, and language tooling — LSP, task runners, debugger, tests — as
+tools that replace or complement an agent's own built-in primitives. A
+structured `read`, for example, returns project knowledge where a raw file read
+returns only bytes.
 
-See [BUILDING.md](./BUILDING.md) for coding rules and conventions, and
-[AGENTS.md](./AGENTS.md) for AI agent instructions.
+These tools are reachable through whatever host fits the workload — an agent
+CLI, or embedded in code as a library (C or WASM) — all calling the same
+runtime. Kraf aims to interoperate with the editors and toolchains a project
+already uses rather than replacing them.
+
+## Related docs
+
+- [docs/README.md](./docs/README.md): documentation index.
+
+- [ARCHITECTURE.md](./docs/ARCHITECTURE.md): architecture.
+- [BUILDING.md](./docs/BUILDING.md): coding rules and conventions.
+- [AGENTS.md](./AGENTS.md): AI agent instructions.