domainforge 0.13.0

package/docs/how-tos/import-from-calm.md

@@ -0,0 +1,114 @@
+# Import from CALM
+
+Goal: Import a FINOS CALM representation into DomainForge, verify integrity, and convert it back to SEA DSL constructs.
+
+## Prerequisites
+
+- SEA CLI built from source (`cargo install --path domainforge-core --features cli`) for validating the imported graph.
+- Access to a CALM JSON file that conforms to the FINOS Architecture-as-Code schema (version `2.0` recommended).
+- Optional bindings:
+  - Python package (`domainforge`) built via `maturin develop` for programmatic import.
+  - TypeScript package (`@godspeedai/domainforge`) built via `npm run build`.
+
+## Steps (be concise)
+
+1. **Inspect the CALM file**
+
+   ```bash
+   jq '.version, .metadata["sea:version"], (.models[0].roles | length)' calm.json
+   ```
+
+   - Confirm the CALM version is `2.0` and that `sea:version` matches the expected SEA baseline (e.g., `0.1.0`).
+
+2. **Import programmatically in Python**
+
+   ```python
+   from domainforge import Graph
+   import json
+
+   calm_json = open("calm.json").read()
+   graph = Graph.import_calm(calm_json)
+
+   print("Entities", graph.entity_count())
+   print("Roles", graph.role_count())
+   ```
+
+   - Use `graph.all_relations()` to confirm relation predicates survived the import.
+   - Call `graph.export_calm()` immediately after import to verify round-trip stability (the output should still be valid CALM JSON).
+
+3. **Import programmatically in TypeScript**
+
+   ```ts
+   import { Graph } from "@godspeedai/domainforge";
+   import { readFileSync } from "fs";
+
+   const calm = readFileSync("calm.json", "utf8");
+   const graph = Graph.importCalm(calm);
+
+   console.log("Flows", graph.flowCount());
+   console.log("Relations", graph.relationCount());
+   ```
+
+   - Re-export with `graph.exportCalm()` to prove the importer produced a valid graph.
+
+4. **Validate the imported graph with the CLI**
+
+   ```bash
+   # Export the imported graph back to CALM then re-parse
+   python - <<'PY'
+   from domainforge import Graph
+   with open('calm.json') as f:
+       data = f.read()
+   graph = Graph.import_calm(data)
+   with open('/tmp/roundtrip.calm.json', 'w') as out:
+       out.write(graph.export_calm())
+   PY
+
+   domainforge import --format kg /tmp/roundtrip.calm.json
+   ```
+
+   - The second command exercises the CLI import pipeline (Turtle/RDF) to ensure the graph can be converted downstream.
+
+5. **Convert CALM to SEA DSL text (Rust)**
+
+   ```rust
+   use domainforge_core::calm::{import, export};
+
+   let calm_json = std::fs::read_to_string("calm.json")?;
+   let graph = import(serde_json::from_str(&calm_json)?)?;
+   // You can now traverse primitives or export to KG/SBVR
+   let exported = export(&graph)?;
+   assert_eq!(exported["metadata"]["sea:version"], domainforge_core::VERSION);
+   ```
+
+   - Although there is no direct CLI flag for CALM → SEA text, the Rust API lets you transform CALM into a `Graph` and then emit other projections (`project --format kg` for Turtle/RDF).
+
+6. **Round-trip verification**
+
+   - Import CALM → Export CALM → Import again. Check that counts for entities/resources/flows/roles/relations remain stable.
+   - Validate units: ensure every `quantity` in CALM includes `unit`; missing units will fail the SEA validator when exporting to DSL.
+
+## Mapping and Normalisation Notes
+
+- Namespaces default to `"default"` when not present; CALM models often omit them. SEA accepts missing namespaces but can enrich them during export.
+- Relations map to `subjectRole`, `predicate`, and `objectRole`; confirm that role IDs in CALM exist in the `roles` array before import.
+- Flows require UUIDs; if a CALM file omits them, the importer will generate deterministic IDs but may warn in the bindings logs.
+- Metadata fields `sea:exported`, `sea:version`, and `sea:timestamp` are preserved; adjust them only if you intentionally re-sign the payload.
+
+## Error Handling and Diagnostics
+
+- **Schema mismatch**: If parsing fails due to a missing field, validate the CALM file against the upstream schema (`ajv validate -s calm.schema.json -d calm.json`).
+- **Unknown role IDs**: Importers raise a `ValueError`/`Error` when a relation references a missing role. Add the role or correct the relation IDs.
+- **Unit conversion failures**: Ensure that every resource or flow quantity uses a defined unit; otherwise, normalization to SEA quantities will fail.
+- **Encoding issues**: CALM must be UTF-8. Re-save files with `iconv -f <encoding> -t utf-8` if you see decoding errors.
+
+## Common Pitfalls / Troubleshooting
+
+- Importing CALM via the CLI is not yet available; use Python/TypeScript/Rust APIs instead, then rely on `domainforge project --format kg` for downstream exports.
+- When working with large models, load the JSON with streaming (`ijson` in Python) if memory is constrained; construct the `Graph` once you validate the structure.
+- Keep the SEA version consistent across files; mixing CALM payloads exported from older SEA versions can surface validation differences.
+
+## Links
+
+- Tutorials: [Getting Started](../tutorials/getting-started.md)
+- Reference: [CALM Mapping](../reference/calm-mapping.md), [CLI Commands](../reference/cli-commands.md), [Python API](../reference/python-api.md), [TypeScript API](../reference/typescript-api.md)

package/docs/how-tos/import-from-sbvr.md

@@ -0,0 +1,249 @@
+# Import from SBVR
+
+This guide explains how to import SBVR (Semantics of Business Vocabulary and Rules) XMI files into SEA graphs.
+
+## Overview
+
+SBVR is an OMG standard for expressing business vocabularies and rules in natural language with formal semantics. DomainForge can import SBVR XMI files and convert them to SEA primitives:
+
+| SBVR Concept  | SEA Mapping         |
+| ------------- | ------------------- |
+| Noun Concept  | Entity              |
+| Verb Concept  | Relation            |
+| Fact Type     | Role-based Relation |
+| Business Rule | Policy              |
+| Definition    | Entity description  |
+
+## Prerequisites
+
+- `sea` CLI installed with `cli` feature
+- An SBVR XMI file (e.g., exported from business rule tools)
+
+## Quick Start
+
+```bash
+# Import SBVR XMI to SEA DSL
+domainforge import --format sbvr vocabulary.xmi > model.sea
+
+# Import with custom namespace
+domainforge import --format sbvr --namespace my-domain vocabulary.xmi
+```
+
+## Example
+
+### Input: SBVR XMI
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<sbvr:Vocabulary xmlns:sbvr="http://www.omg.org/spec/SBVR">
+  <nounConcept xmi:id="nc1" name="Customer">
+    <definition>A person or organization that purchases products</definition>
+  </nounConcept>
+
+  <nounConcept xmi:id="nc2" name="Order">
+    <definition>A request to purchase products</definition>
+  </nounConcept>
+
+  <verbConcept xmi:id="vc1" name="places">
+    <role name="placer" nounConceptRef="nc1"/>
+    <role name="placed" nounConceptRef="nc2"/>
+  </verbConcept>
+
+  <factType xmi:id="ft1" reading="Customer places Order" verbConceptRef="vc1"/>
+
+  <businessRule xmi:id="br1" name="OrderLimit">
+    <statement>Each Customer must have at most 10 pending Orders</statement>
+    <ruleType>OperativeRule</ruleType>
+  </businessRule>
+</sbvr:Vocabulary>
+```
+
+### Output: SEA DSL
+
+```bash
+domainforge import --format sbvr vocabulary.xmi
+```
+
+Produces:
+
+```sea
+Namespace "sbvr"
+
+// Entities from Noun Concepts
+Entity "Customer" {
+    @description "A person or organization that purchases products"
+}
+
+Entity "Order" {
+    @description "A request to purchase products"
+}
+
+// Roles from Verb Concepts
+Role "placer"
+Role "placed"
+
+// Relations from Fact Types
+Relation "places" from placer to placed {
+    @reading "Customer places Order"
+}
+
+// Policies from Business Rules
+Policy "OrderLimit" {
+    severity: error
+    expression: "Each Customer must have at most 10 pending Orders"
+    @original_sbvr true
+}
+```
+
+## SBVR Concept Mapping
+
+### Noun Concepts → Entities
+
+SBVR noun concepts become SEA entities. Concept hierarchies are preserved via the `@generalizes` attribute:
+
+```xml
+<nounConcept xmi:id="nc1" name="Person"/>
+<nounConcept xmi:id="nc2" name="Customer" generalConcept="nc1"/>
+```
+
+Becomes:
+
+```sea
+Entity "Person"
+Entity "Customer" {
+    @generalizes "Person"
+}
+```
+
+### Verb Concepts → Roles and Relations
+
+Binary verb concepts become role definitions and relations:
+
+```xml
+<verbConcept name="manages">
+    <role name="manager" nounConceptRef="Person"/>
+    <role name="managed" nounConceptRef="Team"/>
+</verbConcept>
+```
+
+Becomes:
+
+```sea
+Role "manager"
+Role "managed"
+Relation "manages" from manager to managed
+```
+
+### Business Rules → Policies
+
+Business rules are converted based on their type:
+
+| SBVR Rule Type | SEA Severity |
+| -------------- | ------------ |
+| StructuralRule | error        |
+| OperativeRule  | warning      |
+| DerivationRule | info         |
+
+### Supported Statement Patterns
+
+| SBVR Pattern               | SEA Expression             |
+| -------------------------- | -------------------------- |
+| "Each X must Y"            | `forall x in X: Y(x)`      |
+| "At most one X per Y"      | Cardinality constraint     |
+| "It is necessary that..."  | Policy with error severity |
+| "It is obligatory that..." | Policy with error severity |
+| "It is permitted that..."  | No policy (allowed)        |
+
+## Programmatic Usage
+
+### Rust
+
+```rust
+use domainforge_core::sbvr::SbvrModel;
+
+let xmi = std::fs::read_to_string("vocabulary.xmi")?;
+let sbvr_model = SbvrModel::from_xmi(&xmi)?;
+let graph = sbvr_model.to_graph()?;
+
+println!("Imported {} entities", graph.all_entities().count());
+println!("Imported {} policies", graph.all_policies().count());
+```
+
+### Python
+
+```python
+from domainforge import Graph
+
+# Import SBVR via CLI subprocess
+import subprocess
+result = subprocess.run(
+    ["domainforge", "import", "--format", "sbvr", "vocabulary.xmi"],
+    capture_output=True,
+    text=True
+)
+domainforge = result.stdout
+
+# Parse the resulting SEA DSL
+graph = Graph.parse(domainforge)
+print(f"Imported {len(graph.entities())} entities")
+```
+
+## Limitations
+
+| Limitation           | Workaround                           |
+| -------------------- | ------------------------------------ |
+| Complex quantifiers  | Manual policy authoring after import |
+| Computed derivations | Not supported (logged as warning)    |
+| Temporal rules       | Limited support                      |
+| Modal logic          | Mapped to severity levels            |
+
+Some SBVR statements cannot be automatically converted to SEA expressions. These are imported with `@original_sbvr true` attribute for manual review.
+
+## Post-Import Workflow
+
+1. **Review imported policies**: Check for `@original_sbvr` markers indicating statements that need manual conversion
+2. **Validate the model**: Run `domainforge validate model.sea` to check for semantic errors
+3. **Refine expressions**: Convert natural language statements to formal SEA expressions
+4. **Add missing details**: SBVR may not capture all attributes needed for your domain
+
+```bash
+# Validate imported model
+domainforge validate model.sea
+
+# Export to other formats
+domainforge project --format calm model.sea architecture.json
+domainforge project --format protobuf model.sea contracts.proto
+```
+
+## Troubleshooting
+
+### Parse Error: Invalid XMI
+
+Ensure your SBVR file is valid XMI format:
+
+- Must have proper XML declaration
+- Must use SBVR namespace
+- Element names must match expected tags
+
+### Missing Noun Concepts
+
+If relations reference undefined noun concepts:
+
+1. Check the XMI for `nounConceptRef` values
+2. Ensure all referenced concepts are defined
+3. Use `--allow-unknown` flag to import partial models
+
+### Unsupported Rule Type
+
+Some SBVR rule patterns are not automatically converted:
+
+- The import will succeed with a warning
+- Review the `@original_sbvr` policies manually
+- Convert to formal SEA expressions as needed
+
+## See Also
+
+- [SDS-007: SBVR Import](../specs/SDS-007-sbvr-import.md) - System design spec
+- [Define Policies](./define-policies.md) - Writing SEA policies
+- [CLI Commands](../reference/cli-commands.md) - Import command reference
+- [Grammar Spec](../reference/grammar-spec.md) - SEA syntax reference

package/docs/how-tos/install-cli.md

@@ -0,0 +1,126 @@
+# Install the SEA CLI
+
+Goal: Install and verify the DomainForge SEA CLI on Linux, macOS, and Windows.
+
+## Prerequisites
+
+- Rust toolchain 1.77+ installed via `rustup` (recommended target triples: `x86_64-unknown-linux-gnu`, `x86_64-apple-darwin`, `x86_64-pc-windows-msvc`).
+- Build essentials for your OS (gcc/clang + make on Linux, Xcode CLTs on macOS, Build Tools for Visual Studio on Windows).
+- Optional: `just` for running test recipes.
+
+## Install from Source (recommended until binary releases are published)
+
+1. Clone the repo and install:
+
+```bash
+git clone https://github.com/GodSpeedAI/DomainForge.git
+cd DomainForge
+# For the CLI only
+cargo install --path domainforge-core --features cli
+# If you need SHACL validation (validate-kg), include the shacl feature as well
+cargo install --path domainforge-core --features "cli,shacl"
+```
+
+2. Ensure Cargo bin is on PATH (Linux/macOS):
+
+```bash
+export PATH="$HOME/.cargo/bin:$PATH"
+```
+
+3. Verify the binary:
+
+```bash
+domainforge --version
+domainforge validate --format human domainforge-core/examples/basic.sea
+```
+
+- Expected: version prints `domainforge-core 0.1.0` (or newer) and validation exits successfully.
+
+## Install via GitHub Release (when artifacts are available)
+
+- Download the archive that matches your OS/arch (e.g., `sea-x86_64-unknown-linux-gnu.tar.gz`).
+- Extract and place the `sea` binary on your PATH (`/usr/local/bin` or `%USERPROFILE%\.cargo\bin`).
+- Run `domainforge --version` to confirm the binary is executable.
+
+## Windows-specific Notes
+
+- Use **Developer PowerShell** or **x64 Native Tools Command Prompt** to ensure MSVC is available.
+- Set the default toolchain: `rustup default stable-x86_64-pc-windows-msvc`.
+- If OpenSSL build errors appear, install `vcpkg` and ensure `VCPKGRS_DYNAMIC=1` before running `cargo install`.
+- Ensure Rust binaries are on your PATH in PowerShell:
+
+```powershell
+$env:PATH += ";$HOME\.cargo\bin"
+# Or persist for current user
+setx PATH "$env:PATH;$HOME\.cargo\bin"
+```
+
+## macOS-specific Notes
+
+- Install Xcode Command Line Tools: `xcode-select --install`.
+- On Apple Silicon, prefer the native toolchain; if you need x86_64 binaries, use Rosetta with `arch -x86_64 cargo install ...`.
+
+## Linux-specific Notes
+
+- Ensure `pkg-config` and `openssl-dev` are installed (`sudo apt-get install build-essential pkg-config libssl-dev`).
+- If building inside a container, mount a writable `$CARGO_HOME` to avoid permission errors.
+
+## Running Smoke Tests after Installation
+
+```bash
+# For users installing from source (developer/local builds):
+domainforge validate --format human domainforge-core/examples/basic.sea
+domainforge project --format calm domainforge-core/examples/basic.sea /tmp/basic.calm.json
+domainforge project --format kg domainforge-core/examples/basic.sea /tmp/basic.ttl
+
+# For users installing from a release binary: if `sea` provides a built-in self-check command, run it; otherwise validate using a minimal inline example:
+# Example (if no self-check command exists):
+echo 'entity A {}' > /tmp/minimal.sea
+domainforge validate --format human /tmp/minimal.sea
+```
+
+- These commands confirm parsing, CALM export, and KG export paths.
+
+## Upgrading or Reinstalling
+
+- To force an upgrade after changes: `cargo install --path domainforge-core --features cli --force`.
+- Remove old binaries from other PATH locations to avoid running stale versions.
+
+## Troubleshooting
+
+- **Linker errors on Windows**: reinstall the MSVC build tools and re-run `rustup update`.
+- **Python interference (macOS/Homebrew)**: unset `PYTHONHOME` and rebuild; or create a fresh virtualenv before invoking Cargo to avoid conflicting headers.
+- **Missing OpenSSL**: install `libssl-dev` (Debian/Ubuntu) or `openssl@3` (Homebrew) and set `PKG_CONFIG_PATH` accordingly.
+- **Permission denied**: install to a user-writable directory or run `cargo install` without `sudo`.
+
+## Verification Checklist
+
+- [ ] `domainforge --version` prints the expected version string.
+- [ ] `domainforge validate` succeeds against `domainforge-core/examples/basic.sea`.
+- [ ] `domainforge project --format calm` produces a CALM file containing `sea:version` metadata.
+  - [ ] `domainforge project --format kg` generates Turtle without SHACL errors when run through `domainforge validate-kg` (requires installing with the `shacl` feature: `--features cli,shacl`).
+
+## Links
+
+- Tutorials: [Getting Started](../tutorials/getting-started.md)
+- Reference: [CLI Commands](../reference/cli-commands.md), [Configuration](../reference/configuration.md), [Versioning Strategy](../explanations/versioning-strategy.md)
+
+## Post-install Configuration
+
+- Configure logging verbosity with CLI flags: `--verbose` or `--quiet` (mutually exclusive).
+- Set `SEA_COLOR=always` to force colorized output if your terminal strips ANSI codes.
+- Use `.sea-registry.toml` in your project root to manage namespaces; the CLI discovers it automatically during parse/validate/project commands.
+
+## Example CI Step
+
+```yaml
+- name: Install SEA CLI
+  run: |
+    rustup override set stable
+    cargo install --path domainforge-core --features cli --force
+- name: Validate models
+  run: |
+    domainforge validate --format human models/**/*.sea
+```
+
+- Cache `$CARGO_HOME` between runs to speed up subsequent installs.

package/docs/how-tos/parse-sea-files.md

@@ -0,0 +1,132 @@
+# Parse SEA Files
+
+Goal: Parse `.sea` models using the CLI and programmatic bindings while catching syntax/semantic errors early.
+
+## Prerequisites
+
+- Rust toolchain 1.77+ and the SEA CLI installed.
+
+  - For developers building from this repo: `cargo install --path domainforge-core --features cli` (produces the `sea` binary).
+  - For users installing from crates.io or binaries: use the published `sea` or release artifact; confirm with `domainforge --version`.
+
+- Optional: Python bindings (install locally via `maturin develop --features python` or via PyPI when published) and TypeScript package (`npm install @godspeedai/domainforge` then `npm run build`).
+- A `.sea` source file. Use `domainforge-core/examples/basic.sea` or any model under `examples/` to follow along.
+
+## Steps (be concise)
+
+1. **Validate and parse a single file (CLI)**
+
+   ```bash
+   domainforge validate --format human domainforge-core/examples/basic.sea
+   ```
+
+   - The command parses the file, resolves namespaces from `.sea-registry.toml` when present, and reports semantic errors (unknown entities/resources, unit mismatches).
+   - Use `--format json` for machine-readable diagnostics that include error codes from `validation_error.rs`.
+
+2. **Parse and project to an intermediate representation (CLI)**
+
+   ```bash
+   domainforge project --format calm domainforge-core/examples/basic.sea /tmp/basic.calm.json
+   ```
+
+   - `project` parses the DSL, builds a `Graph`, then exports to CALM JSON. Swap `--format calm` with `--format kg` to emit RDF/Turtle or RDF/XML (auto-detected by extension).
+   - The command fails fast if parsing fails; the error message cites the offending line/column.
+
+3. **Batch-validate multiple files (CLI)**
+
+   ```bash
+   for f in examples/*.sea; do
+     echo "Checking $f"
+     domainforge validate --format human "$f" || exit 1
+   done
+   ```
+
+   - This pattern stops on the first failure. Add `|| true` to continue despite errors.
+
+4. **Generate AST JSON (CLI)**
+
+   ```bash
+   domainforge parse --ast --format json domainforge-core/examples/basic.sea > basic.ast.json
+   ```
+
+   - Produces raw AST JSON preserving source structure and location info.
+   - Useful for feeding tools like `tools/ast_to_ir.py` or writing custom linters.
+
+5. **Parse programmatically in Rust**
+
+   ```rust
+   use domainforge_core::parser::parse_to_graph;
+   ```
+
+let source = std::fs::read_to_string("domainforge-core/examples/basic.sea")?;
+let graph = parse_to_graph(&source)?;
+assert!(graph.entity_count() >= 1);
+
+````
+
+- Prefer `parse_to_graph_with_options` if you need namespace resolution using `NamespaceRegistry::discover`.
+
+6. **Parse programmatically in Python**
+
+```python
+from pathlib import Path
+from domainforge import Graph
+
+text = Path("domainforge-core/examples/basic.sea").read_text()
+
+# Semantic graph parsing
+graph = Graph.parse(text)
+assert graph.resource_count() >= 1
+
+# Raw AST parsing (e.g., for tooling)
+ast_json = Graph.parse_to_ast_json(text)
+````
+
+- Call `graph.all_entities()` or `graph.find_entity_by_name("Customer")` to inspect the parsed model.
+- Errors raise `ValueError` with the same message as the Rust parser.
+
+7. **Parse programmatically in TypeScript**
+
+   ```ts
+   import { readFileSync } from "fs";
+   import { Graph } from "@godspeedai/domainforge";
+
+   const source = readFileSync("domainforge-core/examples/basic.sea", "utf8");
+
+   // Semantic graph parsing
+   const graph = Graph.parse(source);
+   console.log(graph.entityCount());
+
+   // Raw AST parsing
+   const astJson = Graph.parseToAstJson(source);
+   ```
+
+   - Use `graph.allResources()` or `graph.findRoleByName("Payer")` after parsing relation-enabled models.
+
+8. **Handle parse warnings and errors**
+
+   - **Unknown identifiers**: The parser emits `UnknownEntity` or `UnknownResource` errors; add missing declarations or fix typos.
+   - **Unit mismatches**: If a flow references an undefined unit, define it in the `Dimension/Unit` section before the flow.
+   - **Namespace resolution**: If you see `NamespaceMissing`, create `.sea-registry.toml` near the entry file or pass fully qualified names (e.g., `finance/Invoice`).
+
+9. **Integrate parsing into CI**
+
+   ```bash
+   just rust-test  # runs `cargo test -p domainforge-core --features cli` and exercises parser paths
+   just python-test  # rebuilds bindings (maturin develop) and parses DSL fixtures
+   just ts-test  # runs Vitest against `Graph.parse`
+   ```
+
+   - Combine with `cargo fmt --all -- --check` and `cargo clippy -p domainforge-core -- -D warnings` for full validation.
+
+## Common Pitfalls / Troubleshooting
+
+- **Using stale bindings**: After editing grammar or parser code, rebuild Python (`maturin develop`) and TypeScript (`npm run build`) bindings so `Graph.parse` reflects the changes.
+- **File encoding**: Ensure `.sea` files are UTF-8; unusual whitespace can trigger unexpected token errors around indentation-sensitive sections.
+- **Entry path awareness**: When parsing embedded strings (not files), namespace discovery cannot infer the path; pass `ParseOptions` with `entry_path` if you rely on registry lookups.
+- **Large batches**: Wrap CLI calls with `xargs -P` or `GNU parallel` to speed up validation across many files; keep an eye on memory if models are very large.
+
+## Links
+
+- Tutorials: [Getting Started](../tutorials/getting-started.md), [First SEA Model](../tutorials/first-sea-model.md)
+- Reference: [Grammar Spec](../reference/grammar-spec.md), [CLI Commands](../reference/cli-commands.md), [Primitives API](../reference/primitives-api.md)

package/docs/how-tos/policy-evaluation-modes.md

@@ -0,0 +1,30 @@
+# Policy Evaluation Modes (Three-Valued vs Boolean)
+
+Goal: choose and troubleshoot the runtime evaluation mode for policies.
+
+## Defaults and toggle
+
+- Three-valued logic is **enabled by default** (returns `Unknown` when data is missing).
+- Switch to strict boolean mode when you need binary pass/fail:
+  - Rust: `graph.set_evaluation_mode(false)`
+  - Python: `graph.set_evaluation_mode(False)`
+  - TypeScript/WASM: `graph.setEvaluationMode(false)`
+
+Return to three-valued logic with `true/True`.
+
+## When to use which mode
+
+- **Three-valued (default)**: modeling in-progress systems; want Unknown instead of false negatives.
+- **Boolean**: production gates that must fail on any missing data; CI pipelines that treat Unknown as failure.
+
+## Symptoms and fixes
+
+- Seeing `Unknown` results when you expect pass/fail: enable boolean mode for that run or complete the missing fields.
+- Tests failing after switching modes: ensure fixtures set `graph.set_evaluation_mode(true/false)` explicitly.
+- Performance concerns: toggling is runtime-only; no rebuild needed.
+
+## See also
+
+- [Policy Evaluation Logic](../explanations/policy-evaluation-logic.md)
+- [Three-Valued Logic](../explanations/three-valued-logic.md)
+- [CLI Commands](../reference/cli-commands.md) (`--allow-unknown` parallels three-valued behavior)