MontrealAI · MontrealAI · Jun 10, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -13,13 +13,30 @@ Contributions must preserve the proof-led, public-safe foundation of the reposit
 
 ## Required local checks
 
+Prefer the maintained aggregate target:
+
+```bash
+make validate
+```
+
+The target runs the required guardrail commands:
+
 ```bash
 python scripts/check_no_paid_artifacts.py
-python scripts/validate_goalos_public_site.py
-python scripts/validate_docs_tables_figures.py
 python scripts/validate_goalos_catalog.py
+python scripts/validate_docs_tables_figures.py
+python scripts/validate_goalos_public_site.py
 ```
 
+Run `make test` for the Python test suite when dependencies are available. If a check cannot run because of a local environment limitation, document the exact command, failure, and limitation in the PR.
+
+
+## Documentation upkeep
+
+- Keep `README.md`, `docs/GOALOS_DOCUMENTATION_INDEX.md`, `docs/api_reference.md`, `QA_VERIFICATION.md`, and `Makefile` synchronized when local commands, API routes, validation order, or canonical product facts change.
+- Prefer current package names (`proof_gradient` / `proof-gradient`) in new instructions; only mention legacy SkillOS names in explicitly archived historical material.
+- Keep generated public-site changes traceable to source docs, catalog data, validation scripts, or GitHub Actions inputs.
+
 ## Public product boundary
 
 Buyer products may be mentioned publicly, but public downloads must route to https://www.quebecartificialintelligence.com/shop and must not expose paid deliverables in this repository.
diff --git a/Makefile b/Makefile
@@ -1,16 +1,34 @@
-.PHONY: demo serve test pages clean
+.PHONY: help demo api serve test validate pages clean
+
+help:
+	@printf '%s\n' \
+		'Proof Gradient developer commands:' \
+		'  make demo      Run the local customer-response proof demo' \
+		'  make api       Start the FastAPI app on 127.0.0.1:8000' \
+		'  make test      Run the Python test suite with pytest' \
+		'  make validate  Run public-safe GoalOS documentation/site validators' \
+		'  make pages     Build the generated GitHub Pages site' \
+		'  make clean     Remove local build, cache, and SQLite artifacts'
 
 demo:
-	python -m skillos.cli demo
+	python -m proof_gradient demo --json
+
+api:
+	python -m proof_gradient api --host 127.0.0.1 --port 8000
 
-serve:
-	python -m skillos.cli serve
+serve: api
 
 test:
-	python -m unittest discover -s tests -v
+	pytest
+
+validate:
+	python scripts/check_no_paid_artifacts.py
+	python scripts/validate_goalos_catalog.py
+	python scripts/validate_docs_tables_figures.py
+	python scripts/validate_goalos_public_site.py
 
 pages:
 	python scripts/build_pages.py
 
 clean:
-	rm -rf .skillos dist build *.egg-info
+	rm -rf .pytest_cache .ruff_cache dist build *.egg-info proof_gradient.db
diff --git a/QA_VERIFICATION.md b/QA_VERIFICATION.md
@@ -6,14 +6,26 @@ GoalOS Validation Hotfix v14 Microsite Compatibility is current. v12, v13, and o
 
 ## Required commands
 
+Prefer the aggregate Make target:
+
+```bash
+make validate
+```
+
+The target runs the required guardrail commands:
+
 ```bash
 python scripts/check_no_paid_artifacts.py
-python scripts/validate_goalos_public_site.py
-python scripts/validate_docs_tables_figures.py
 python scripts/validate_goalos_catalog.py
+python scripts/validate_docs_tables_figures.py
+python scripts/validate_goalos_public_site.py
 ```
 
 
+## Current branch verification — 2026-06-10
+
+Documentation and developer-command refresh validated the current public-safe guardrail path with `make validate`. A direct `pytest` run initially stopped during collection because this environment did not have the Starlette test-client transport packages (`httpx2`/`httpx`) installed. After installing the project development extras with `python -m pip install -e ".[dev]"`, `pytest` passed with 85 tests and 2 FastAPI/Starlette deprecation warnings.
+
 ## Merge-readiness result — 2026-06-09
 
 Final repository validation for the institutional upgrade used the required GoalOS guardrail commands, the GoalOS Cloud MVP Node test, and optional Python test suites. The only environment note was the need to install `httpx2` and `httpx` locally before running FastAPI/Starlette test-client tests; after installation, `pytest` and `make test` both passed.

diff --git a/README.md b/README.md
@@ -95,8 +95,24 @@ Current path: v14 validation hotfix → Public Site Release v8 Intelligent Asset
 
 Public repo may include public docs, standards, schemas, examples, proof pages, site assets, and the narrow AEP package exception `standards/AEP-###/complete-package.zip`. Public repo must not include paid buyer ZIPs, workshop bundles, buyer/facilitator delivery kits, implementation bundles, enterprise pilot bundles, commercialization packs, private legal/tax packs, keys, treasury secrets, or seed phrases.
 
+## Local developer quick start
+
+Install the package with development dependencies in your preferred virtual environment, then use the Make targets as the stable local interface:
+
+```bash
+python -m pip install -e ".[dev]"
+make demo
+make api
+make test
+make validate
+```
+
+The API listens on `http://127.0.0.1:8000` by default when launched with `make api`. See [Proof Gradient API Reference](docs/api_reference.md) for the current endpoint list and CLI companion commands.
+
 ## Validation and QA
 
+Use `make validate` or run the required guardrail commands directly:
+
 ```bash
 python scripts/check_no_paid_artifacts.py
 python scripts/validate_goalos_catalog.py
@@ -114,13 +130,15 @@ python scripts/validate_goalos_public_site.py
 | `docs/figures/` | Mermaid sources and SVG companions |
 | `badges/` | truthful static badges |
 | `scripts/` | validation and site automation scripts |
+| `proof_gradient/` | local API, CLI, proof services, database models, and providers |
+| `schemas/` | public JSON schemas for proof/run/release/artifact contracts |
 | `.github/workflows/` | autonomous validation/release workflows |
 | `site/` | generated public site deploy root |
 | `standards/` and `docs/standards/` | AEP public standards |
 
 ## Documentation map
 
-Start with [GoalOS Documentation Index](docs/GOALOS_DOCUMENTATION_INDEX.md), [Product Ladder](docs/GOALOS_PRODUCT_LADDER.md), [Website Autonomous Actions](docs/GOALOS_WEBSITE_AUTONOMOUS_ACTIONS.md), [Paid Artifact Policy](docs/GOALOS_PAID_ARTIFACT_POLICY.md), [$JOBS Overview](docs/JOBS_ON_BASE_OVERVIEW.md), and [Repository Audit](docs/GOALOS_REPO_AUDIT.md).
+Start with [GoalOS Documentation Index](docs/GOALOS_DOCUMENTATION_INDEX.md), [Product Ladder](docs/GOALOS_PRODUCT_LADDER.md), [Website Autonomous Actions](docs/GOALOS_WEBSITE_AUTONOMOUS_ACTIONS.md), [Paid Artifact Policy](docs/GOALOS_PAID_ARTIFACT_POLICY.md), [$JOBS Overview](docs/JOBS_ON_BASE_OVERVIEW.md), [Proof Gradient API Reference](docs/api_reference.md), and [Repository Audit](docs/GOALOS_REPO_AUDIT.md).
 
 ## Figures and tables
 

diff --git a/docs/GOALOS_DOCUMENTATION_INDEX.md b/docs/GOALOS_DOCUMENTATION_INDEX.md
@@ -16,7 +16,7 @@ This index is the official navigation map for Proof Gradient · GoalOS. Source o
 12. **$JOBS technical status and mainnet gates** — [Technical status](JOBS_ON_BASE_TECHNICAL_STATUS.md), [Mainnet gates](JOBS_ON_BASE_MAINNET_GATES.md), [Audit handoff](JOBS_ON_BASE_AUDIT_HANDOFF.md)
 13. **Commercialization plan** — [Plan](COMMERCIALIZATION_PLAN.md), [Status](GOALOS_COMMERCIALIZATION_STATUS.md), [Team scorecard](COMMERCIALIZATION_TEAM_SCORECARD.md), [Proof of value](COMMERCIALIZATION_PROOF_OF_VALUE.md), [Performance vault](COMMERCIALIZATION_PERFORMANCE_VAULT.md)
 14. **Website autonomous GitHub Actions** — [Website autonomous actions](GOALOS_WEBSITE_AUTONOMOUS_ACTIONS.md), [Public site release v8](GOALOS_PUBLIC_SITE_RELEASE_V8.md)
-15. **Validation and CI** — [Validation hotfix v14](GOALOS_VALIDATION_HOTFIX_V14.md), [Catalog validator](../scripts/validate_goalos_catalog.py), [Docs/tables/figures validator](../scripts/validate_docs_tables_figures.py)
+15. **Validation, CI, and local API** — [Validation hotfix v14](GOALOS_VALIDATION_HOTFIX_V14.md), [API reference](api_reference.md), [Catalog validator](../scripts/validate_goalos_catalog.py), [Docs/tables/figures validator](../scripts/validate_docs_tables_figures.py)
 16. **Paid-file policy** — [Paid artifact policy](GOALOS_PAID_ARTIFACT_POLICY.md)
 17. **Figures** — [Figure inventory](tables/goalos_figure_inventory.csv), [Figures directory](figures/)
 18. **Tables** — [Tables directory](tables/)

diff --git a/docs/api_reference.md b/docs/api_reference.md
@@ -1,95 +1,155 @@
-# API Reference
+# Proof Gradient API Reference
 
-Run the server:
+This reference covers the local FastAPI service exposed by `proof_gradient.api`. It is intentionally limited to public-safe platform endpoints that can be exercised against a local SQLite database.
+
+## Run the server
+
+From the repository root:
+
+```bash
+python -m proof_gradient api --host 127.0.0.1 --port 8000
+```
+
+Equivalent Make target:
 
 ```bash
-python -m skillos.cli serve
+make api
 ```
 
 Base URL:
 
 ```text
-http://127.0.0.1:8765
+http://127.0.0.1:8000
 ```
 
-## Health
+The API initializes the configured database at startup. The default local database is `sqlite:///./proof_gradient.db` unless `PROOF_GRADIENT_DATABASE_URL` is set.
+
+## Operational endpoints
+
+### Health
 
 ```http
-GET /api/health
+GET /healthz
 ```
 
-## Dashboard
+Returns service liveness:
 
-```http
-GET /api/dashboard
+```json
+{
+  "status": "ok",
+  "service": "proof-gradient"
+}
 ```
 
-## Skills
+### Readiness
 
 ```http
-GET /api/skills
+GET /readyz
 ```
 
-## Lessons
+Checks database access and returns:
+
+```json
+{
+  "status": "ready"
+}
+```
+
+### Metrics
 
 ```http
-GET /api/lessons
+GET /metrics
 ```
 
-## Run job
+Returns Prometheus-style counters for artifacts, runs, proofs, patches, and rollouts.
+
+## Tenant setup
+
+### Create tenant
 
 ```http
-POST /api/jobs
+POST /tenants
+Content-Type: application/json
 ```
 
 ```json
 {
-  "goal": "Draft a sales follow-up email from call notes",
-  "agent_id": "sales_agent",
-  "inputs": {
-    "prospect_name": "Maya",
-    "company_name": "Orion Labs",
-    "agreed_next_step": "review the pilot plan on Friday"
-  },
-  "human_edits": "Moved the next step to the opening lines."
+  "name": "demo"
 }
 ```
 
-## Discover lessons
+The service creates the tenant and a local owner identity for that tenant.
+
+## Demo workflow
+
+### Run customer-response demo
 
 ```http
-POST /api/learn
+POST /demo/run
+Content-Type: application/json
 ```
 
 ```json
 {
-  "min_support": 3
+  "tenant": "demo",
+  "prompt": "Draft a response to this angry customer asking for a refund."
 }
 ```
 
-## Train candidate skill
+The demo exercises the proof-led workflow loop and returns the generated run, artifacts, proof, patch, rollout, and selection outputs.
+
+## Query endpoints
+
+All query endpoints accept an optional `tenant` query parameter. If omitted, the default tenant is `demo`.
+
+### List artifacts
 
 ```http
-POST /api/train
+GET /artifacts?tenant=demo
 ```
 
-```json
-{
-  "lesson_id": "lesson_abc123"
-}
+Returns artifact IDs, names, artifact types, and risk classes for the tenant.
+
+### List runs
+
+```http
+GET /runs?tenant=demo
 ```
 
-## Approve release
+Returns run IDs, statuses, and job IDs for the tenant.
+
+### List proofs
 
 ```http
-POST /api/approve
+GET /proofs?tenant=demo
 ```
 
-```json
-{
-  "skill_id": "sales_followup_email",
-  "version": 2,
-  "scope": "team",
-  "rollout": "10_percent_canary"
-}
+Returns proof IDs, associated run IDs, and checksums for the tenant.
+
+## CLI companions
+
+The same local platform can be exercised without starting the API:
+
+```bash
+python -m proof_gradient demo --json
+python -m proof_gradient artifact list --tenant demo
+python -m proof_gradient proof list --tenant demo
+python -m proof_gradient selection list --tenant demo
+```
+
+## Validation before publishing docs or site changes
+
+Run the public-safe validation suite before opening a PR:
+
+```bash
+make validate
+```
+
+or run the underlying commands directly:
+
+```bash
+python scripts/check_no_paid_artifacts.py
+python scripts/validate_goalos_catalog.py
+python scripts/validate_docs_tables_figures.py
+python scripts/validate_goalos_public_site.py
 ```