Stele — third-party readiness — investigation — v0.1

Version. 0.1 Date. 2026-06-20 Author. Claude Code (CC) on DUNIN7-M4, read-only inspection; for Marvin Percival (DUNIN7 Operator). Status. Findings document. Pre-scoping readiness assessment; no CR. Markdown primary (technical consumer). Read-only inspection of DUNIN7/stele main 8246729; nothing changed. Reports and characterises; recommends nothing; designs nothing.

Plain-language summary

The question: how ready is the standalone Stele package for a third party who will clone it, read it, run it, test it, and possibly install it into their own app? A stranger gets only what is in the repository — not what lives in loomworks-record.

The core is solid; the packaging skin is half-done. Stele installs without the engine (all dependencies are public PyPI packages, no path-dep), the reference host + browser ceremony + config generator all ship and run, the tree is clean (no hardcoded paths, no secrets), and the inline docstrings are rich. But the front door is stale (the root README still describes the P7-1 state, points at no examples, and tells the reader to set the wrong environment variable), there is no test suite in the repo at all (the tests/ directory is empty; no CI), the best adopter document doesn't ship (the mount-contract guide lives only in loomworks-record), and the legal/publication surface is unresolved (metadata says Proprietary, there is no LICENSE file, and the repo is private). Two items are Operator/legal decisions, not build work: the license and publication.

Per-item verdicts: 1 PARTIAL · 2 PARTIAL · 3 MISSING · 4 PRESENT · 5 PRESENT · 6 PARTIAL · 7 DECISION · 8 mostly clean (one doc breaker).

1. Front door (root README) — PARTIAL

• A repo-root README.md exists (34 lines). It leads well:

> "Stele — A standalone identity & authentication substrate: principals (UUID identity), WebAuthn passkeys, TOTP, and recovery codes. No host framework dependency — Stele is a library of primitives plus its own database schema."

• But it is stale to the P7-1 state. Its Status block reads: "P7-1 packaging floor (CR-2026-114). … The SDK surface and mountable router are P7-2; the reference app and full docs are P7-3" — i.e. it describes P7-2 and P7-3 as future, though both have shipped.
• "What's here" lists only src/stele/ and migrations/ — it does not mention examples/ (the reference app, the browser ceremony, the generator), the mountable stele.router, or the adopter docs.
• Its "Clone-and-run" block stops at alembic upgrade head and sets the wrong variable: export LOOMWORKS_SECRET_KEY=… — the package reads STELE_SECRET_KEY (renamed at P7-2). A reader following the root README sets a variable the package ignores. (See §8.)
• The separate examples/README.md is current and good (§4); the root README does not point to it.

2. Install path — PARTIAL

• pyproject.toml declares: name = "stele", version = "0.1.0", requires-python = ">=3.12", build backend hatchling, packages = ["src/stele"] → pip-installable.
• No engine assumption in Stele's own manifest. Every dependency is a public PyPI package: sqlalchemy[asyncio], pydantic, webauthn, pyotp, bcrypt, cryptography, asyncpg, alembic, fastapi. There is no ../engine, no ../stele, no editable path-dep anywhere in the manifest. Stele installs with the engine absent; in a clean environment the dependencies resolve.
• Gaps for a stranger installing today:
• No version tag on the repo (git tag → 0 tags). A developer cannot pip install …@<tag> today.
• Dependencies are exact-pinned (==) to the engine's resolved versions. In a host app's environment these exact pins can conflict (e.g. a host on a different SQLAlchemy). The manifest comment acknowledges this: "P7-3 / publishing may relax these to ranges; P7-1 is deliberately conservative."
• The repo is private (git@github.com:DUNIN7/stele.git). A third party cannot clone or pip install git+… without being granted access — a publication decision (§7).
• Version is 0.1.0 (not bumped for the P7-2/P7-3 work).

3. Test path — MISSING

• tests/ is empty — zero test files in the repo. (Stele has never had its own pytest suite; verification through P7-3 was done with ad-hoc CC scripts patching the two WebAuthn library calls, run outside the repo, plus the engine's consuming suite — none of which ships here.)
• No test/dev dependency group in pyproject.toml — pytest / httpx are not declared.
• No CI — there is no .github/workflows/ (or any CI config) in the tree.
• There is no documented "clone, run tests, see green" path, and nothing to run it against. A stranger cannot exercise a suite against a throwaway Postgres because there is no suite.

4. Examples — PRESENT (with run caveats)

• examples/ inventory (all present): reference_app/{__init__,config,db,main}.py, reference_app/static/{app.js,index.html}, generate_env.py, docker-compose.yml, README.md.
• The examples/README.md walks a complete clone-to-running path: install stele (pip install -e ..), python generate_env.py > .env, docker compose up -d (throwaway Postgres on :5433), alembic upgrade head, uvicorn reference_app.main:app --port 8000, open http://localhost:8000. It names the RP-origin-match gotcha prominently.
• Internally consistent: the docker-compose service (stele:stele@…:5433/stele_ref), the generator's default STELE_DATABASE_URL, and the README all agree on port/user/db.
• Run caveats (not defects, but a stranger must meet them): needs a real Postgres (Docker or local — SQLite is not viable, the models use JSONB/bytea) and Python 3.12; the live passkey step needs a real authenticator in a browser (manual, not automatable); uvicorn reference_app.main:app is run from the examples/ directory so the reference_app package imports. The non-browser path (signup → login → enrollment, both delivery shapes) was verified end-to-end against a real Postgres during the P7-3 build.

5. The generator — PRESENT

• examples/generate_env.py at HEAD emits the full env floor: STELE_SECRET_KEY (freshly generated — re-confirmed a valid Fernet key at HEAD), STELE_RP_ID, STELE_RP_NAME, STELE_RP_ORIGIN, STELE_DATABASE_URL (template = the docker-compose URL), and a commented optional STELE_SECRET_KEYS_PREVIOUS (rotation).
• Completeness check passes: reference_app/config.py requires exactly STELE_SECRET_KEY + STELE_DATABASE_URL (the RP fields and cookie name have defaults) — the generator emits both required vars plus the RP fields. The emitted .env is complete for the reference app.
• Note the contrast with §1/§8: the generator uses the correct STELE_… names; the root README still uses LOOMWORKS_SECRET_KEY.

6. Documentation — PARTIAL (a ship-gap)

• Ships IN the package (what a cloner gets): the root README (stale, §1); examples/README.md (current, good); and rich inline docstrings on every module, including the mount-contract example embedded in src/stele/__init__.py's module docstring (the FastAPI mount + the injection slots).
• Does NOT ship in the package (a cloner cannot see it): the polished adopter mount-contract guide (standards/loomworks-stele-mount-contract-v0_1.{md,html}) lives only in loomworks-record. A third party with the package cannot reach it (the record is private/behind access).
• The gap: the single best adopter-facing document — the one that names the two required slots, the authorization boundary, the cookie-vs-bearer choice, the walkthrough, the RP-origin gotcha, and no-email-as-identity — is invisible to anyone who only has the repository.

7. License / legal surface — OPERATOR / LEGAL DECISION (not build)

• pyproject.toml declares license = { text = "Proprietary" }.
• There is no LICENSE / COPYING file at the repo root.
• There are no copyright / SPDX headers in src/stele/*.py.
• So: the metadata asserts Proprietary, but no license text ships and no per-file headers exist. Against the stated open-source-publication intent (noted in the §19.1 principal-nature disposition), "Proprietary" metadata with no LICENSE is an unresolved contradiction. Reported as fact only — the choice is the Operator's.

8. Clean-checkout breakers — MOSTLY CLEAN; one real doc breaker

• No hardcoded /Users/dunin7 or DUNIN7-M4 paths in any tracked file. ✓
• No .env and no secrets tracked. .gitignore correctly excludes .env, .venv/, __pycache__/, .py[cod], .egg-info/, dist/, build/, .pytest_cache/. ✓
• Engine/record references in tracked files are comments only — pyproject.toml:10 (pin-provenance, "what loomworks-engine resolves at fe7c3f1") and migrations/versions/0001_baseline.py:6 (baseline provenance). Naming the source repo in a comment; no functional dependency. Cosmetic.
• One real breaker (doc-only): README.md:25 tells the reader to export LOOMWORKS_SECRET_KEY=…, but the package reads STELE_SECRET_KEY. A stranger following the root README sets a variable the package ignores. (src/stele/kek.py:19–20 also mentions LOOMWORKS_SECRET_KEY, but only in explanatory docstring prose about the rename — harmless.)
• The private repo is not a checkout breaker per se, but a stranger cannot obtain the checkout without access (publication decision, §2/§7).

Gap list (the shape of the finishing work)

PRESENT (done)

• The reference host + browser WebAuthn ceremony + config generator + docker-compose + a complete examples/README.md walkthrough. [#4, #5]
• A self-contained, pip-installable pyproject.toml: all-PyPI dependencies, no engine path-dep, requires-python pinned. [#2 — mechanism]
• Rich inline docstrings, including the mount example in __init__. [#6]
• Clean tree hygiene: no hardcoded paths, no committed secrets, correct .gitignore. [#8]

PARTIAL (what's missing to finish an existing item)

• Root README refresh — bring it to current state (P7-2 + P7-3 shipped), fix the env var to STELE_SECRET_KEY, add examples/ + the mountable-router path, extend "clone-and-run" past the migration to the reference app. [#1, #8]
• Install path — cut a version tag; decide whether to relax the == pins to ranges for host-env compatibility; bump the version. [#2]
• Ship the adopter docs — bring the mount-contract guide (record-only today) into the repo so a cloner can read it. [#6]

MISSING (net-new build)

• An in-repo test suite + a test/dev dependency group (pytest/httpx) + a documented one-command "clone, run tests, see green" path against a throwaway Postgres. [#3]
• CI config (.github/workflows/ or equivalent). [#3]

Operator / legal DECISIONS (not build work)

• License — resolve Proprietary metadata vs the absent LICENSE file vs the open-source-publication intent; add a LICENSE file (and optionally SPDX headers) once chosen. [#7]
• Publication — the repo is private; making it cloneable / installable by a third party (public repo and/or a PyPI release) is a publication decision. [#2, #8]

DUNIN7 — Done In Seven LLC — Miami, Florida Stele — third-party readiness — investigation — v0.1 — 2026-06-20