docs: add spec docs for environment module

.gitignore

@@ -82,4 +82,4 @@
 
 !/.agents
 !/.agents/**
-!/.agents/**/*
+!/.agents/**/*

AGENTS.md

@@ -5,3 +5,6 @@ tags: [agents, instructions, repository, coding-conventions]
 ---
 
 See [BUILDING.md](./BUILDING.md) for coding rules and conventions.
+
+Agent skills live in [.agents/skills/](./.agents/skills/). Each skill's
+`SKILL.md` front-matter describes when to use it.

BUILDING.md

@@ -66,16 +66,16 @@ which Docker can't build for.
 
 ## Markdown front-matter
 
-Every `.md` file requires frontmatter with `title`, `summary`, and `tags` —
+Every `.md` file requires front-matter with `title`, `summary`, and `tags` —
 makes docs easy to index for agents. Exception: the root `README.md`, which
-doesn't need frontmatter. Module `README.md` files do need it — see
+doesn't need front-matter. Module `README.md` files do need it — see
 [Module README](./docs/README.md#readme-readmemd).
 
 ## Agents
 
 Don't commit AI agent config that's exclusive to a single agent (Claude-only,
-Codex-only, etc.) — it lives in the dev's own environment. Config meant to
-work across agents may be committed.
+Codex-only, etc.) — it lives in the dev's own environment. Config meant to work
+across agents may be committed.
 
 ## Code standards
 

README.md

@@ -2,24 +2,24 @@
 
 Kraf is a neutral layer for humans and autonomous agents, designed to provide a
 consistent way to work with software projects across tools, environments, and
-vendors — without vendor lock-in. The goal is to start a development
-environment with the least possible friction, and fast.
+vendors — without vendor lock-in. The goal is to start a development environment
+with the least possible friction, and fast.
 
 ## Summary
 
 Kraf explores a portable, vendor-neutral foundation for developer and agent
-environments. Rather than replacing the tools, configuration files, or
-workflows a project already uses, Kraf resolves them into an environment
-plan, then materializes it wherever it's needed — a local shell today; CI,
-containers, or an airgapped agent later. Materialization targets change;
-the resolved plan doesn't.
+environments. Rather than replacing the tools, configuration files, or workflows
+a project already uses, Kraf resolves them into an environment plan, then
+materializes it wherever it's needed — a local shell today; CI, containers, or
+an airgapped agent later. Materialization targets change; the resolved plan
+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.
+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.
 
 ## Contributing
 

docs/README.md

@@ -27,9 +27,9 @@ Documentation lives with the feature it describes. Never in root /docs
 <feature>/
 └── docs/
     ├── <feature>-intent.md
-    └── <area>/
-        ├── <area>.spec.md
-        └── <area>.acceptance.md
+    └── <feature>-<area>/
+        ├── <feature>-<area>.spec.md
+        └── <feature>-<area>.acceptance.md
 ```
 
 Documentation does not need to map one-to-one to source files, platform files,
@@ -95,12 +95,17 @@ tags: [<tag1>, <tag2>, ...]
 > sources planned for its evolution. It does not imply that all of these
 > capabilities are already implemented.
 
+## Overview
+
+<Free-form, detailed description of the module: its model, concepts, and how
+they relate. May use subsections (###).>
+
 ## Documentation
 
 - [Intent](./docs/<feature>-intent.md): purpose, boundaries, and evolution of
   this module.
-- [<Area>](./docs/<area>/<area>.spec.md): <area> requirements and acceptance
-  scenarios.
+- [<Area>](./docs/<feature>-<area>/<feature>-<area>.spec.md): <area>
+  requirements and acceptance scenarios.
 ```
 
 ### Intent (*.intent.md)
@@ -132,7 +137,7 @@ tags: [<tag1>, <tag2>, ...]
 ## Documentation
 
 - [Readme](../README.md): module overview.
-- [<Area>](./<area>/<area>.spec.md): <area> Specification.
+- [<Area>](./<feature>-<area>/<feature>-<area>.spec.md): <area> Specification.
 ```
 
 ### Specification (*.spec.md)
@@ -173,7 +178,7 @@ THEN THE SOFTWARE SHALL <behavior>.
 
 **Layout:**
 
-```md
+````md
 ---
 title: <Area> - SPEC
 summary: <One-line summary of the requirements.>
@@ -196,18 +201,20 @@ Name: <Requirement name>
 
 **Links:**
 
-- [<FEATURE>_<AREA>-ACC-0001](./<area>.acceptance.md#<feature>_<area>-acc-0001)
+- [<FEATURE>_<AREA>-ACC-0001](./<feature>-<area>.acceptance.md#<feature>_<area>-acc-0001)
 - [Intent](../<feature>-intent.md)
 
 **Status**:
 
 - Doc status: Draft
 - Implementation status: Not implemented
 
-**WHEN:** <event>,
+```text
+WHEN: <event>,
 
-**THE SOFTWARE SHALL:** <behavior>.
+THE SOFTWARE SHALL: <behavior>.
 ```
+````
 
 ### Acceptance (*.acceptance.md)
 
@@ -259,7 +266,7 @@ Name: <Scenario name>
 
 **Links:**
 
-- [<FEATURE>_<AREA>-REQ-0001](./<area>.spec.md#<feature>_<area>-req-0001)
+- [<FEATURE>_<AREA>-REQ-0001](./<feature>-<area>.spec.md#<feature>_<area>-req-0001)
 
 **Status**:
 

docs/example/example.spec.md

@@ -20,14 +20,16 @@ Name: Explicit configuration
 
 **Links:**
 
-- [EXAMPLE_AREA-ACC-0001](./example.acceptance.md#example_area-acc-0001)
 - [Intent](../example-intent.md)
+- [EXAMPLE_AREA-ACC-0001](./example.acceptance.md#example_area-acc-0001)
 
 **Status**:
 
 - Doc status: Draft
 - Implementation status: Not implemented
 
-**WHEN:** Configuration provides an unknown key,
+```text
+WHEN: Configuration provides an unknown key,
 
-**THE SOFTWARE SHALL:** reject the configuration.
+THE SOFTWARE SHALL: reject the configuration.
+```

src/environment/src/env_var/README.md

@@ -0,0 +1,77 @@
+---
+title: Environment variables
+summary: Declarative model, resolution, and projection of environment variables in Kraf.
+tags: [environment, env-var, resolution, projection]
+---
+
+This module defines and resolves Kraf's declarative model for environment
+variables: their sources (host, organization, user, project, and session),
+aliases, and projections exported to Kraf-managed processes.
+
+> **Note:** this document describes Kraf's environment-variable model, including
+> concepts and sources planned for its evolution. It does not imply that all of
+> these capabilities are already implemented.
+
+## Overview
+
+- [**Sources**](#sources): where environment-variable values, configuration, and
+  restrictions come from.
+- [**Declaration**](#declarations): the canonical definition of a variable.
+- [**Resolver**](#resolution): the component that applies declarations to values
+  from sources to produce an effective value.
+- [**Projection**](#projection): the set of effective variables that Kraf
+  exports to a managed process.
+
+### Sources
+
+- **Host:** provides values available in the current environment and platform.
+- **User:** provides persistent personal preferences.
+- **Organization:** provides shared configuration and policies enforced by the
+  organization.
+- **Project:** provides versioned, project-specific configuration.
+- **Session:** provides ephemeral values controlled by Kraf.
+
+### Declarations
+
+A canonical definition of a variable in Kraf. A declaration specifies:
+
+- its canonical key;
+- import and export aliases;
+- sources eligible to provide a value;
+- resolution strategy;
+- fallback;
+- keys that may be projected to a child process.
+
+### Resolution
+
+The resolver applies declarations to values available from sources and produces
+the effective value of each variable.
+
+For each declaration, it defines:
+
+- precedence between sources;
+- how values are combined, when applicable;
+- how conflicts or missing values are handled;
+- when a fallback is applied;
+- how placeholders in values and fallbacks are expanded.
+
+### Projection
+
+A projection is the set of effective variables exported by Kraf to a managed
+process.
+
+A declaration can produce one internal canonical key and zero or more export
+keys. Not every resolved value must be projected to a child process.
+
+## Documentation
+
+- [Intent](./docs/env-var-intent.md): purpose, boundaries, and evolution of this
+  module.
+- [Declarations](./docs/env-var-declarations/env-var-declarations.spec.md):
+  declaration requirements and acceptance scenarios.
+- [Resolution](./docs/env-var-resolution/env-var-resolution.spec.md): resolution
+  requirements and acceptance scenarios.
+- [Projection](./docs/env-var-projection/env-var-projection.spec.md): projection
+  requirements and acceptance scenarios.
+- [Host mappings](./docs/env-var-host/env-var-host.spec.md): platform mapping
+  requirements and acceptance scenarios.