docs: update TUI persona schema, add UKO vocabulary extensions module guide, add ACMS to API index

- docs/api/tui.md: Fix Persona dataclass to reflect actual Pydantic model with all fields (icon, greeting, color, cycle_order, base_arguments, scoped_projects, scoped_plans). Add PersonaPreset docs and effective_arguments() method. Add txt export format to /session:export and CLI session export commands. - docs/api/index.md: Add cleveragents.acms entry linking to reference/acms.md. - docs/modules/uko-vocabulary-extensions.md: New module guide covering Layer 2 paradigm vocabularies (uko-oo, uko-func, uko-proc) and Layer 3 technology vocabularies (uko-py, uko-ts, uko-rs, uko-java) with usage examples, DetailLevelMap inheritance, and VocabularyRegistry API. - mkdocs.yml: Add Module Guides nav section with shell-safety, uko-provenance, and uko-vocabulary-extensions pages.
2026-04-09 00:42:00 +00:00
parent 92f533dcff
commit 5048862207
4 changed files with 435 additions and 10 deletions
@@ -18,6 +18,7 @@ classes, functions, and exceptions with signatures and usage examples.
 | [`cleveragents.config`](config.md) | Application settings, logging, metrics, and security scanning |
 | [`cleveragents.providers`](providers.md) | AI provider registry — discovery, selection, LLM factory, and capability metadata |
 | [`cleveragents.tui`](tui.md) | Interactive Terminal UI — app, persona system, input routing, slash commands, session export/import |
+| [`cleveragents.acms`](../reference/acms.md) | Advanced Context Management System — three-tier context strategy, UKO runtime, vocabulary extensions |

 > **Note:** Internal modules (prefixed with `_`) and implementation details
 > not listed in a module's `__all__` are considered private and may change
@@ -90,13 +90,53 @@ registry.ensure_default(actor="openai/gpt-4o")  # create default if absent

 ### `Persona`

+Pydantic model persisted as a YAML file in `~/.config/cleveragents/personas/`.
+
 ```python
-@dataclass
-class Persona:
-    name: str
-    actor: str
-    presets: list[ArgumentPreset]
-    scope_refs: list[str]
+from cleveragents.tui.persona import Persona, PersonaPreset
+
+class Persona(BaseModel):
+    name: str                          # unique identifier; no path/control chars
+    description: str = ""             # human-readable description
+    icon: str = ""                     # emoji or single char shown in tab labels
+    actor: str                         # namespaced actor ref, e.g. "openai/gpt-4o"
+    color: str | None = None           # optional accent colour for the persona bar
+    base_arguments: dict = {}          # default argument overrides applied to all presets
+    scoped_projects: list[str] = []    # project names this persona is scoped to
+    scoped_plans: list[str] = []       # plan IDs this persona is scoped to
+    argument_presets: list[PersonaPreset] = []  # named argument override presets
+    cycle_order: int = 0               # position in Ctrl+T cycling order
+    greeting: str = ""                 # message shown when persona is activated
+```
+
+**Invariants enforced by validators:**
+
+- `actor` must be namespaced (`namespace/name` format).
+- `name` must not contain `/`, `\`, `..`, null bytes, or control characters.
+- `argument_presets` always contains exactly one preset named `"default"` with empty overrides.
+  If none is provided, a default preset is created automatically.
+
+### `PersonaPreset`
+
+```python
+class PersonaPreset(BaseModel):
+    name: str      # preset identifier (e.g. "default", "verbose")
+    display: str   # human-readable label shown in the UI
+    overrides: dict = {}  # argument overrides merged on top of base_arguments
+```
+
+### `Persona.effective_arguments(preset_name=None) → dict`
+
+Computes the effective argument dict for a given preset using shallow merge:
+
+```python
+persona = registry.get("my-persona")
+
+# Base arguments only (no preset)
+args = persona.effective_arguments()
+
+# Base arguments merged with "verbose" preset overrides
+args = persona.effective_arguments("verbose")
 ```

 ---
@@ -140,20 +180,31 @@ Tool, Skill, Invariant, Profile, Context, Utility.

 | Command | Description |
 |---------|-------------|
-| `/session:export [--format json\|md] [path]` | Export session to JSON or Markdown |
+| `/session:export [--format json\|md\|txt] [path]` | Export session to JSON, Markdown, or plain text |
 | `/session:import <path>` | Import a session from a JSON file |

 ```python
-# Export as Markdown transcript
+# Export as canonical JSON (default; importable)
+/session:export ~/my-session.json
+
+# Export as Markdown transcript (human-readable, not importable)
 /session:export --format md ~/my-session.md

-# Export as canonical JSON (default)
-/session:export ~/my-session.json
+# Export as plain-text transcript (for piping into other tools)
+/session:export --format txt ~/my-session.txt

 # Import a previously exported session
 /session:import ~/my-session.json
 ```

+**Format comparison:**
+
+| Format | Importable | Use case |
+|--------|-----------|----------|
+| `json` (default) | ✅ Yes | Backup, migration, round-trip |
+| `md` | ❌ No | Sharing, documentation, human review |
+| `txt` | ❌ No | Piping into other tools, plain-text processing |
+
 ---

 ## Session Export / Import
@@ -183,6 +234,9 @@ agents session export --session-id <ID> --output session.json
 # Export as Markdown transcript (human-readable, not importable)
 agents session export --session-id <ID> --output session.md --format md

+# Export as plain-text transcript (for piping into other tools)
+agents session export --session-id <ID> --output session.txt --format txt
+
 # Import from JSON
 agents session import --input session.json
 ```
@@ -0,0 +1,366 @@
+# UKO Vocabulary Extensions (Layer 2 & Layer 3)
+
+**Package:** `cleveragents.acms.uko`
+**Introduced:** v3.6.0 (UKO Runtime), extended in v3.8.0
+
+This module guide covers the Layer 2 paradigm vocabularies and Layer 3
+technology-specific vocabulary extensions of the Universal Knowledge Ontology
+(UKO) runtime.  These extensions refine the base Layer 0/1 ontology with
+programming-paradigm and language-specific semantic concepts.
+
+For the full UKO runtime API reference, see
+[`docs/reference/uko_runtime.md`](../reference/uko_runtime.md).
+For the Layer 2 vocabulary reference, see
+[`docs/reference/uko_layer2_paradigm_vocabularies.md`](../reference/uko_layer2_paradigm_vocabularies.md).
+For the Layer 3 vocabulary reference, see
+[`docs/reference/uko_layer3_technology_vocabularies.md`](../reference/uko_layer3_technology_vocabularies.md).
+
+---
+
+## Architecture Overview
+
+The UKO vocabulary system is organized into four layers:
+
+```
+Layer 0 (uko:)       — Universal foundation: Container, Atom, Boundary, dependsOn
+Layer 1 (uko-code:)  — Code domain: TypeDefinition, Callable, Module, File
+Layer 2 (uko-oo/func/proc:) — Paradigm specializations
+Layer 3 (uko-py/ts/rs/java:) — Language-specific refinements
+```
+
+Each layer inherits from the layer above it via `rdfs:subClassOf` and
+`rdfs:subPropertyOf` relationships.  The `DetailLevelMap` inheritance chain
+allows child layers to insert new named detail levels without breaking parent
+level semantics.
+
+---
+
+## Layer 2: Paradigm Vocabularies
+
+Layer 2 provides three paradigm-specific vocabulary namespaces.
+
+### Object-Oriented (`uko-oo:`)
+
+**Namespace:** `https://cleveragents.ai/ontology/uko/oo#`
+
+```python
+from cleveragents.acms.uko.vocabularies import get_oo_vocabulary
+
+vocab = get_oo_vocabulary()
+oo_class = vocab.get_class("Class")
+oo_method = vocab.get_class("Method")
+```
+
+**Key classes:**
+
+| Class | Superclass | Description |
+|-------|-----------|-------------|
+| `uko-oo:Class` | `uko-code:TypeDefinition`, `uko:Container` | OO class containing methods and attributes |
+| `uko-oo:Interface` | `uko-code:TypeDefinition`, `uko:Boundary` | Interface or abstract base class |
+| `uko-oo:Method` | `uko-code:Callable` | Method defined within a class |
+| `uko-oo:Attribute` | `uko:Atom` | Class or instance attribute |
+
+**Key properties:**
+
+| Property | Domain | Range | Description |
+|----------|--------|-------|-------------|
+| `uko-oo:inheritsFrom` | `uko-oo:Class` | `uko-oo:Class` | Inheritance relationship |
+| `uko-oo:implements` | `uko-oo:Class` | `uko-oo:Interface` | Interface implementation |
+
+**DetailLevelMap insertions** (added on top of `uko-code:` base map):
+
+| Depth | Name | Description |
+|-------|------|-------------|
+| 3 | `CLASS_HIERARCHY` | Inheritance chains and interface implementations |
+| 7 | `VISIBILITY_ANNOTATED` | Public/protected/private modifiers |
+
+### Functional (`uko-func:`)
+
+**Namespace:** `https://cleveragents.ai/ontology/uko/func#`
+
+```python
+from cleveragents.acms.uko.vocabularies import get_func_vocabulary
+
+vocab = get_func_vocabulary()
+```
+
+**Key classes:**
+
+| Class | Superclass | Description |
+|-------|-----------|-------------|
+| `uko-func:PureFunction` | `uko-code:Callable` | Pure function with no side effects |
+| `uko-func:TypeClass` | `uko-code:TypeDefinition`, `uko:Boundary` | Type class defining operations for types |
+| `uko-func:Monad` | `uko-code:TypeDefinition` | Monadic type encapsulating computation context |
+
+### Procedural (`uko-proc:`)
+
+**Namespace:** `https://cleveragents.ai/ontology/uko/proc#`
+
+```python
+from cleveragents.acms.uko.vocabularies import get_proc_vocabulary
+
+vocab = get_proc_vocabulary()
+```
+
+**Key classes:**
+
+| Class | Superclass | Description |
+|-------|-----------|-------------|
+| `uko-proc:ProceduralFunction` | `uko-code:Callable` | Procedural function declaration |
+| `uko-proc:GlobalVariable` | `uko:Atom` | Global variable declaration |
+| `uko-proc:HeaderFile` | `uko:Container` | Header file defining exported declarations |
+| `uko-proc:StructDefinition` | `uko-code:TypeDefinition` | C-style struct type definition |
+| `uko-proc:Macro` | `uko:Atom` | Preprocessor macro definition |
+
+---
+
+## Layer 3: Technology Vocabularies
+
+Layer 3 provides language-specific vocabulary extensions that further
+specialize Layer 2 paradigm concepts.
+
+### Python (`uko-py:`)
+
+**Namespace:** `https://cleveragents.ai/ontology/uko/py#`
+
+```python
+from cleveragents.acms.uko.layer3_py import (
+    PYTHON_VOCABULARY,
+    PYTHON_DETAIL_LEVELS,
+    PythonClass,
+    PythonFunction,
+    PythonModule,
+    PythonDecorator,
+    PythonTypeStub,
+)
+```
+
+**Key classes:**
+
+| Class | Superclass | Description |
+|-------|-----------|-------------|
+| `uko-py:PythonClass` | `uko-oo:Class` | Python class (supports multiple inheritance) |
+| `uko-py:PythonFunction` | `uko-func:PureFunction` | Python function or method |
+| `uko-py:PythonModule` | `uko-code:Module` | Python module (`.py` file) |
+| `uko-py:PythonDecorator` | `uko:Atom` | Python decorator applied to a class or function |
+| `uko-py:PythonTypeStub` | `uko:Atom` | Type stub (`.pyi` file) |
+
+**Usage example:**
+
+```python
+from cleveragents.acms.uko.layer3_py import PYTHON_VOCABULARY, PYTHON_DETAIL_LEVELS
+
+# Resolve a named detail level for Python
+depth = PYTHON_DETAIL_LEVELS.resolve("CLASS_HIERARCHY")
+# → integer depth in the effective map
+
+# Get the Python vocabulary
+py_class = PYTHON_VOCABULARY.get_class("PythonClass")
+```
+
+### TypeScript (`uko-ts:`)
+
+**Namespace:** `https://cleveragents.ai/ontology/uko/ts#`
+
+```python
+from cleveragents.acms.uko.layer3_ts import (
+    TYPESCRIPT_VOCABULARY,
+    TYPESCRIPT_DETAIL_LEVELS,
+    TypeScriptClass,
+    TypeScriptFunction,
+    TypeScriptInterface,
+    TypeScriptModule,
+)
+```
+
+**Key classes:**
+
+| Class | Superclass | Description |
+|-------|-----------|-------------|
+| `uko-ts:TypeScriptClass` | `uko-oo:Class` | TypeScript class |
+| `uko-ts:TypeScriptFunction` | `uko-func:PureFunction` | TypeScript function |
+| `uko-ts:TypeScriptInterface` | `uko-oo:Interface` | TypeScript interface |
+| `uko-ts:TypeScriptModule` | `uko-code:Module` | TypeScript module (`.ts` / `.tsx` file) |
+
+### Rust (`uko-rs:`)
+
+**Namespace:** `https://cleveragents.ai/ontology/uko/rs#`
+
+```python
+from cleveragents.acms.uko.layer3_rs import (
+    RUST_VOCABULARY,
+    RUST_DETAIL_LEVELS,
+    RustStruct,
+    RustTrait,
+    RustImpl,
+    RustFunction,
+    RustDeriveAttribute,
+)
+```
+
+**Key classes:**
+
+| Class | Superclass | Description |
+|-------|-----------|-------------|
+| `uko-rs:RustStruct` | `uko-proc:StructDefinition` | Rust struct |
+| `uko-rs:RustTrait` | `uko-oo:Interface` | Rust trait |
+| `uko-rs:RustImpl` | `uko:Container` | Rust `impl` block |
+| `uko-rs:RustFunction` | `uko-func:PureFunction` | Rust function |
+| `uko-rs:RustDeriveAttribute` | `uko:Atom` | Rust `#[derive(...)]` attribute |
+
+### Java (`uko-java:`)
+
+**Namespace:** `https://cleveragents.ai/ontology/uko/java#`
+
+```python
+from cleveragents.acms.uko.layer3_java import (
+    JAVA_VOCABULARY,
+    JAVA_DETAIL_LEVELS,
+    JavaClass,
+    JavaInterface,
+    JavaMethod,
+    JavaAnnotation,
+    JavaCheckedException,
+)
+```
+
+**Key classes:**
+
+| Class | Superclass | Description |
+|-------|-----------|-------------|
+| `uko-java:JavaClass` | `uko-oo:Class` | Java class |
+| `uko-java:JavaInterface` | `uko-oo:Interface` | Java interface |
+| `uko-java:JavaMethod` | `uko-oo:Method` | Java method |
+| `uko-java:JavaAnnotation` | `uko:Atom` | Java annotation (`@Annotation`) |
+| `uko-java:JavaCheckedException` | `uko:Atom` | Java checked exception declaration |
+
+---
+
+## DetailLevelMap Inheritance
+
+The `DetailLevelMap` inheritance chain resolves named levels by walking up
+the map hierarchy from most-specific to least-specific:
+
+```
+Layer 3 (uko-py:) → Layer 2 (uko-oo:) → Layer 1 (uko-code:) → Layer 0 (uko:)
+```
+
+### Building a Custom Map
+
+```python
+from cleveragents.acms.uko.detail_level_maps import (
+    CODE_DETAIL_LEVEL_MAP,
+    OO_DETAIL_LEVEL_MAP,
+    DetailLevelMapBuilder,
+    build_effective_map,
+)
+
+# Build a custom map that extends OO with a new level
+builder = DetailLevelMapBuilder(OO_DETAIL_LEVEL_MAP, "my-lang:")
+builder.insert_after("CLASS_HIERARCHY", "MIXIN_RESOLUTION")
+my_map = builder.build()
+
+# Resolve a named level
+depth = my_map.resolve("MIXIN_RESOLUTION")
+```
+
+### `build_effective_map(maps)`
+
+Merges multiple `DetailLevelMap` objects into a single effective map,
+resolving conflicts by preferring the most-specific (last) map:
+
+```python
+from cleveragents.acms.uko.detail_level_maps import build_effective_map
+
+effective = build_effective_map([
+    CODE_DETAIL_LEVEL_MAP,
+    OO_DETAIL_LEVEL_MAP,
+    PYTHON_DETAIL_LEVELS,
+])
+```
+
+---
+
+## VocabularyRegistry
+
+The `VocabularyRegistry` provides a unified lookup across all registered
+paradigm vocabularies:
+
+```python
+from cleveragents.acms.uko.vocabulary_registry import VocabularyRegistry, DuplicateVocabularyError
+from cleveragents.acms.uko.vocabularies import (
+    get_oo_vocabulary,
+    get_func_vocabulary,
+    get_proc_vocabulary,
+)
+
+registry = VocabularyRegistry(
+    vocabularies=(
+        get_oo_vocabulary(),
+        get_func_vocabulary(),
+        get_proc_vocabulary(),
+    )
+)
+
+# Look up a vocabulary by namespace prefix
+oo = registry.get_by_prefix("uko-oo:")
+assert oo is not None
+
+# Look up a class across all vocabularies
+cls = registry.find_class("uko-oo:Class")
+```
+
+**`DuplicateVocabularyError`** is raised when two vocabularies share the
+same namespace prefix.
+
+---
+
+## Base Vocabulary Types
+
+These types are shared across all layers and are the building blocks for
+vocabulary definitions:
+
+```python
+from cleveragents.acms.uko.vocabulary import (
+    UKOVocabulary,
+    UKOClass,
+    UKOProperty,
+    Layer2Dependency,
+    ProvenanceInfo,
+    build_detail_level_map,
+    resolve_detail_level,
+)
+```
+
+| Type | Description |
+|------|-------------|
+| `UKOVocabulary` | Container for a set of OWL classes and properties |
+| `UKOClass` | OWL class definition with superclasses and description |
+| `UKOProperty` | OWL property definition with domain, range, and superproperty |
+| `Layer2Dependency` | Declares a dependency on a Layer 2 vocabulary URI |
+| `ProvenanceInfo` | Provenance metadata for vocabulary definitions |
+
+---
+
+## Gotchas
+
+- **Layer 1 (`uko-code:`) Python module is not yet implemented.** The Python
+  code works standalone using the `DetailLevelMap` from `crp.py`, but full
+  OWL reasoning against Layer 1 URIs is not available.
+- **Turtle files are validated by `UKOLoader` but not by a full OWL reasoner.**
+  Structural validation is performed; semantic entailment is not.
+- **Procedural vocabulary classes are inferred from spec rendering tables.**
+  Explicit Turtle definitions for `uko-proc:` are pending.
+- **`DuplicateVocabularyError` is raised eagerly at registry construction.**
+  Ensure each vocabulary has a unique namespace prefix before registering.
+
+---
+
+## Related Documentation
+
+- [UKO Runtime Services](../reference/uko_runtime.md) — full API reference
+- [UKO Ontology](../reference/uko.md) — four-layer ontology and provenance property definitions
+- [UKO Layer 2 Paradigm Vocabularies](../reference/uko_layer2_paradigm_vocabularies.md) — detailed class/property tables
+- [UKO Layer 3 Technology Vocabularies](../reference/uko_layer3_technology_vocabularies.md) — language-specific vocabulary details
+- [UKO Provenance Tracking](uko-provenance.md) — provenance metadata and temporal versioning
+- [ACMS](../reference/acms.md) — how UKO feeds into context assembly
@@ -32,6 +32,10 @@ nav:
    - Ops Runbook: development/ops-runbook.md
    - System Watchdog: development/system-watchdog.md
    - Automation Tracking: development/automation-tracking.md
+  - Module Guides:
+    - Shell Safety: modules/shell-safety.md
+    - UKO Provenance Tracking: modules/uko-provenance.md
+    - UKO Vocabulary Extensions: modules/uko-vocabulary-extensions.md
  - Implementation Timeline: timeline.md
  - FAQ: faq.md
  - Reference: reference/