[codex] Align Base120 SDK docs with package contract

README.md

@@ -1,95 +1,118 @@
 # Base120
 
-> **v1 Python validator RETIRED (2026-04-14).** The original v1 validator
-> code is no longer the active surface. The canonical registry
-> (`Base120_Canonical_Model_Registry.yaml`) and data files (`registries/`)
-> remain here as source of truth.
->
-> **v2 Python SDK is active (scaffolding in `base120/`):** `cli.py`, `engine.py`,
-> `models.py`, `ledger.py`, `mcp_server.py`. Version line `2.0.0.dev0` per
-> `pyproject.toml`. See `GOVERNANCE.md` for the contract authority and change
-> taxonomy that govern this SDK.
+> **Lifecycle note (2026-05-24).** The original v1 validator runtime was
+> retired on 2026-04-14. This repository now contains the active stdlib-only
+> Python v2 SDK (`base120` 2.0.0.dev0) for operator lookup, prompting, MCP
+> serving, and VERUM-aligned ledger records.
+> The canonical v1 registry (`Base120_Canonical_Model_Registry.yaml`) and data
+> files (`registries/`) remain here as source of truth.
 >
 > **FM taxonomy (FM1–FM30) migrated to:**
 > [`hummbl-governance`](https://github.com/hummbl-dev/hummbl-governance)
 > — `from hummbl_governance.errors import FailureMode, HummblError`
 >
-> **MCP server (TypeScript, live):**
-> [`mcp-server`](https://github.com/hummbl-dev/mcp-server) — all 120 operators served via MCP
+> **MCP server:** use the Python `base120-mcp` entry point from this package,
+> or the external [`mcp-server`](https://github.com/hummbl-dev/mcp-server)
+> mirror when a TypeScript server is required.
 
 [![License: Apache 2.0](https://img.shields.io/badge/license-Apache_2.0-blue)](LICENSE)
 
 **120 mental models for structured reasoning.** Use them to analyze problems, design systems, and make decisions — whether you are a human, an AI agent, or a fleet of both.
 
 ## Quick Example
 
-Apply a model to decompose a problem:
+Apply an operator, generate a prompt, and persist a governance-readable record:
 
 ```python
-from base120.validators.validate import validate_artifact
-
-# FM42: Separation of Concerns -- does this component have a single responsibility?
-artifact = {
-    "id": "auth-service-review",
-    "domain": "core",
-    "class": "architecture",
-    "instance": "auth-svc",
-    "models": ["FM42"]    # Separation of Concerns
-}
-errors = validate_artifact(artifact, schema, mappings, err_registry)
-# [] -- valid artifact, model applies cleanly
+from base120 import Engine, Ledger
+
+engine = Engine()
+
+operator = engine.get("P6")
+print(operator.name)  # Point-of-View Anchoring
+
+prompt = engine.prompt("P6", "How should we price the certification tier?")
+result = engine.record(
+    "P6",
+    "How should we price the certification tier?",
+    "Anchor the offer to the compliance officer's risk budget.",
+    0.85,
+)
+
+ledger = Ledger("base120-ledger.jsonl")
+ledger.append(result.to_tuple())
 ```
 
-Each of the 120 models is a named, versioned reasoning primitive with a defined domain, failure graph, and validation rules.
+Each of the 120 operators is a named, versioned reasoning primitive with a
+defined transformation family and deterministic package representation.
 
 ## Features
 
-- **120 mental models** across 6 cognitive domains (core, systems, security, governance, operations, meta)
-- **6 cognitive transformations** -- deterministic operations that compose models into chains
-- **CLI validation** -- `base120 validate-contract` checks governance artifacts against the frozen spec
-- **Observability layer** -- opt-in structured JSON events for production monitoring
-- **MCP integration** -- serve models to AI agents via [mcp-server](https://github.com/hummbl-dev/mcp-server)
-- **Golden corpus** -- all implementations must match the canonical test corpus in `tests/corpus`
+- **120 reasoning operators** across 6 transformation families
+- **Stdlib-only Python SDK** -- no third-party runtime dependencies
+- **CLI tooling** -- `base120 list`, `base120 get`, `base120 prompt`, and `base120 families`
+- **Append-only ledger** -- persist operator applications as VERUM-aligned JSONL tuples
+- **MCP integration** -- serve operators to AI agents with the `base120-mcp` entry point
+- **Canonical registry and corpus docs** -- frozen v1 reference artifacts remain in-tree
 
-## Install
+## Install From Source
 
 ```bash
-pip install base120
-
-# Or from source
 git clone https://github.com/hummbl-dev/base120.git && cd base120
 pip install -e ".[test]"
 ```
 
+The package name is `base120`, but this repository should not claim PyPI
+availability until a published package exists.
+
 ## CLI
 
 ```bash
-# Validate a contract unit (schema, failure graph, version metadata)
-base120 validate-contract path/to/contract.json
+# List all operators
+base120 list
+
+# Inspect one operator
+base120 get P6
+
+# Generate an operator-specific prompt for a problem
+base120 prompt P6 "How should we price the certification tier?"
+
+# List canonical operator families
+base120 families
 ```
 
-See [`docs/contract-units.md`](docs/contract-units.md) for contract unit format and examples.
+The historical contract-unit validator spec is archived in
+[`docs/contract-units.md`](docs/contract-units.md); the current v2 SDK does not
+ship `base120 validate-contract`.
 
-## Observability
+## Ledger
 
-Opt-in structured events for production deployments:
+Persist operator applications as JSONL tuples:
 
 ```python
-from base120.observability import create_event_sink
+from base120 import Engine, Ledger
 
-event_sink = create_event_sink()  # logs to stdout
-errors = validate_artifact(artifact, schema, mappings, err_registry,
-                          event_sink=event_sink)
-# Emits: {"event_type": "validator_result", "result": "success", ...}
+engine = Engine()
+result = engine.record("DE1", "Reduce release risk.", "Split blockers by owner.", 0.9)
+
+ledger = Ledger()
+ledger.append(result.to_tuple())
+high_drift = ledger.cut(0.5)
 ```
 
-Omitting `event_sink` preserves original v1.0.0 behavior with zero overhead. Full spec: [`docs/observability.md`](docs/observability.md).
+The archived v1 validator observability contract remains in
+[`docs/observability.md`](docs/observability.md), but the current v2 SDK does
+not expose `base120.observability`.
 
 ## Authority Statement
 
-This repository is the **authoritative reference implementation** for Base120 v1.0.0. All other language implementations are semantic mirrors and MUST conform exactly to the outputs defined here.
+This repository is the **authoritative source** for the Base120 v1 registry,
+reference artifacts, and current Python v2 SDK. Other language
+implementations should conform to the frozen registry and corpus artifacts
+defined here. The `2.0.0.dev0` Python SDK API remains pre-release until a
+non-dev package version is published.
 
-### v1.0.x Policy
+### v1 Artifact Policy
 
 - **Permitted:** Security fixes, CI hardening, documentation, corpus additions
 - **Prohibited:** Schema changes, registry modifications, breaking changes
@@ -125,3 +148,7 @@ Apache 2.0 -- see [LICENSE](LICENSE).
 ---
 
 Built by [HUMMBL LLC](https://hummbl.io). Base120 powers the cognitive layer behind multi-agent coordination at scale.
+
+## Repository Health
+
+See [docs/REPO_HEALTH.md](docs/REPO_HEALTH.md) for validation and branch-protection expectations.

docs/REPO_HEALTH.md

@@ -5,13 +5,13 @@
 - **Repository**: `hummbl-dev/base120`
 - **Canonical URL**: `https://github.com/hummbl-dev/base120`
 - **Owner**: HUMMBL Team
-- **Stewardship scope**: Canonical Base120 registry, executable corpus contract, governance specs, and v1 reference artifacts.
+- **Stewardship scope**: Canonical Base120 registry, executable corpus contract, governance specs, v1 reference artifacts, and the active Python v2 SDK.
 
 ## Lifecycle
 
-- **Status**: Active public repository with the Python v1 package retired.
+- **Status**: Active public repository with frozen v1 registry/corpus artifacts and an active Python v2 SDK (`base120` 2.0.0.dev0).
 - **Default branch**: `main`.
-- **Release posture**: v1 Python runtime code has been removed. Registry, corpus, governance, documentation, and CI hardening changes may continue through pull requests.
+- **Release posture**: The v1 validator runtime is retired. The current Python package exposes operator lookup, prompting, MCP serving, and VERUM-aligned ledger records; registry, corpus, governance, documentation, and CI hardening changes may continue through pull requests.
 - **Archive trigger**: Archive only if the canonical Base120 registry and corpus contract move to another declared source of truth.
 
 ## Source Of Truth
@@ -21,7 +21,8 @@
 - `tests/corpus/` is the canonical executable corpus path for Base120 contract artifacts.
 - `docs/corpus-contract.md` and `mirrors/CONFORMANCE_CONTRACT.md` document the corpus contract for implementations and mirrors.
 - `GOVERNANCE.md` and `docs/governance-decision-tree.md` define change classes and review expectations.
-- `docs/contract-units.md` defines contract unit structure and examples.
+- `docs/contract-units.md` defines archived v1 contract unit structure and examples; the current v2 SDK does not ship the `base120 validate-contract` command.
+- `base120/` contains the active v2 SDK package.
 
 ## Validation Contract
 
@@ -32,6 +33,7 @@ python -m pip install --upgrade pip
 pip install -e ".[test]"
 pytest
 python -m pytest tests/ -v
+python -m pip wheel . --no-deps -w dist-smoke
 ```
 
 Expected CI coverage:
@@ -53,15 +55,16 @@ Expected CI coverage:
 ## Known Operational Gaps
 
 - GitHub branch protection is tracked centrally in `hummbl-dev/hummbl-dev#18`; do not overclaim required checks until that audit is updated.
-- The Python v1 package is retired, so validation should focus on registry, corpus, and mirror-conformance integrity rather than runtime feature growth.
+- The Python v1 validator package is retired, while the v2 SDK is active pre-release. Keep README/API docs aligned with the actual `Engine`, `Ledger`, CLI, and MCP entry points.
+- `docs/contract-units.md` and `docs/observability.md` are archived v1 validator contracts, not current v2 SDK API promises.
 - `tests/test_corpus_contract.py` validates that `tests/corpus/` exists, has valid/invalid JSON artifacts, and has expected-error manifests for every invalid artifact.
 
 ## Fleet Scan Classification
 
 Future fleet scans can classify this repository as:
 
-- **Lifecycle**: active, v1 runtime retired
+- **Lifecycle**: active, v1 validator runtime retired, v2 SDK pre-release active
 - **Visibility**: public
-- **Primary function**: canonical Base120 registry and executable corpus contract
+- **Primary function**: canonical Base120 registry, executable corpus contract, and active stdlib-only Python SDK
 - **Validation entrypoint**: `pytest`
 - **Primary metadata owner**: HUMMBL Team

docs/contract-units.md

@@ -1,5 +1,11 @@
 # Base120 Contract Units
 
+> **Status (2026-05-24): archived v1 validator contract.** The current
+> `base120` v2 SDK does not implement the `base120 validate-contract` command.
+> The CLI examples below document the retired validator surface and must not be
+> treated as current package behavior unless validator support is reintroduced
+> with tests.
+
 ## Overview
 
 Contract units are the **core governance artifacts** in Base120. They serve as **executable specifications** that define:
@@ -25,12 +31,19 @@ Contract units are **independent governance artifacts** but MUST align with Base
 
 ## CLI Usage
 
-### Installation
+This section is historical. For current SDK commands, use `base120 list`,
+`base120 get`, `base120 prompt`, and `base120 families`.
+
+### Historical Installation
 
-Install Base120 with pip:
+The retired validator was once installed as a package. Do not use this snippet
+as current release guidance; the active v2 SDK is installed from this source
+tree until a package is published.
 
 ```bash
-pip install base120
+git clone https://github.com/hummbl-dev/base120.git
+cd base120
+python -m pip install -e ".[test]"
 ```
 
 ### Validating a Contract Unit
@@ -339,8 +352,8 @@ jobs:
         uses: actions/setup-python@v4
         with:
           python-version: '3.12'
-      - name: Install Base120
-        run: pip install base120
+      - name: Install Base120 from source
+        run: python -m pip install -e ".[test]"
       - name: Validate Contract
         run: base120 validate-contract contracts/service-contract.json
 ```

docs/observability.md

@@ -1,9 +1,14 @@
 # Base120 Observability Contract
 
-**Version:** v1.0.0  
-**Status:** Governance-guaranteed (Indicated work)  
+**Version:** v1.0.0
+**Status:** Archived v1 validator contract
 **Failure Mode Addressed:** FM19 (Observability Failure)
 
+> **Current SDK note (2026-05-24):** the `base120` v2 SDK does not expose
+> `base120.validators` or `base120.observability`. This document preserves the
+> retired v1 validator observability contract; it is not a current package API
+> promise.
+
 ---
 
 ## Purpose

tests/test_docs_current_contract.py

@@ -0,0 +1,77 @@
+"""Public documentation checks for the current Base120 package surface."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import tomllib
+
+import base120
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def _read(relative: str) -> str:
+    return (ROOT / relative).read_text(encoding="utf-8")
+
+
+def _flat(text: str) -> str:
+    return " ".join(text.split())
+
+
+def test_readme_advertises_current_sdk_surface() -> None:
+    readme = _read("README.md")
+    flat_readme = _flat(readme)
+
+    unsupported_claims = [
+        "Python code has been removed",
+        "base120 validate-contract path/to",
+        "from base120.validators",
+        "from base120.observability",
+        "pip install base120",
+    ]
+    for claim in unsupported_claims:
+        assert claim not in readme
+
+    assert "does not ship `base120 validate-contract`" in flat_readme
+    assert "does not expose `base120.observability`" in flat_readme
+    assert "from base120 import Engine, Ledger" in readme
+    assert "base120 list" in readme
+    assert "base120 get P6" in readme
+    assert "base120 prompt P6" in readme
+    assert "base120 families" in readme
+    assert "should not claim PyPI availability" in flat_readme
+
+
+def test_archived_validator_docs_are_marked_as_archived() -> None:
+    archived_docs = [
+        "docs/contract-units.md",
+        "docs/observability.md",
+    ]
+
+    for relative in archived_docs:
+        text = _read(relative)
+        lower_text = text.lower()
+        assert "archived v1 validator contract" in lower_text
+        assert "current" in lower_text
+        assert "v2 sdk does not" in lower_text
+
+
+def test_current_docs_do_not_claim_pypi_install() -> None:
+    docs_to_check = [
+        "README.md",
+        "docs/contract-units.md",
+        "docs/observability.md",
+    ]
+
+    for relative in docs_to_check:
+        assert "pip install base120" not in _read(relative)
+
+
+def test_documented_sdk_version_matches_package_metadata() -> None:
+    pyproject = tomllib.loads((ROOT / "pyproject.toml").read_text(encoding="utf-8"))
+    version = pyproject["project"]["version"]
+
+    assert base120.__version__ == version
+    assert version in _read("README.md")
+    assert version in _read("docs/REPO_HEALTH.md")