stapel-docs 0.1.0__tar.gz

stapel_docs-0.1.0/CONFIG.MD

@@ -0,0 +1,65 @@
+# CONFIG.MD — stapel-docs
+
+Config registry for **stapel-docs** (`static-scaffold-and-config.md` §2).
+One row per configuration key the module reads, its **source** (`env` = the
+process environment / the `STAPEL_DOCS` settings dict), what it is for,
+whether it is required, and its default.
+
+All keys are read through `docs_settings`
+(`stapel_docs.conf.AppSettings`, namespace `STAPEL_DOCS`).
+Resolution order per key: `settings.STAPEL_DOCS` dict → a flat Django
+setting of the same name → environment variable → the default below.
+`STORAGE` is resolved with `import_string` (dotted path). `SHARING` is one
+nested dict key; its sub-keys are listed as `SHARING.<KEY>` rows below.
+
+## stapel-docs
+
+### Storage seam & presigned URLs (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| STORAGE | env | dotted path to a DocsStorage implementation (REPLACE) — every byte of document content I/O goes through it. | no | stapel_docs.storage.DjangoStorageBackend |
+| STORAGE_PREFIX | env | object-key prefix: `{STORAGE_PREFIX}/{workspace_id}/{document_id}/…`. | no | docs |
+| UPLOAD_URL_EXPIRES_SECONDS | env | presigned PUT URL lifetime (upload tickets). | no | 900 |
+| DOWNLOAD_URL_EXPIRES_SECONDS | env | presigned GET URL lifetime (downloads). | no | 3600 |
+
+### S3Backend (extra `[s3]`; read only when STORAGE points at it) (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| S3_ENDPOINT_URL | env | S3/MinIO endpoint URL (None = AWS default). | no | None |
+| S3_PUBLIC_URL | env | public base URL substituted into presigned URLs (split-horizon deployments). | no | None |
+| S3_ACCESS_KEY | env | access key id. | no | None |
+| S3_SECRET_KEY | env | secret access key. | no | None |
+| S3_REGION | env | bucket region. | no | us-east-1 |
+| S3_BUCKET | env | bucket name. | no | stapel-docs |
+| S3_CONNECT_TIMEOUT | env | botocore connect timeout (seconds) — tight on purpose; a fast failure beats a spinner. | no | 5 |
+| S3_READ_TIMEOUT | env | botocore read timeout (seconds). | no | 15 |
+| S3_MAX_ATTEMPTS | env | botocore retry ceiling. | no | 2 |
+
+### Registries & seams (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| DOC_TYPES | env | document-type registry overlay merged OVER the txt/md/csv/file builtins ({slug: dotted-path to DocTypeSpec \| None removes}). | no | {} |
+| EXPORTERS | env | export-format registry overlay merged OVER the built-in pdf ({format: dotted-path \| None removes}). | no | {} |
+| INGEST | env | event-driven ingest ({action_name: dotted-path mapper payload → create_document kwargs}); broken entries raise ImproperlyConfigured at wiring. | no | {} |
+
+### Journal / revisions / tree / trash (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| REPLAY_WINDOW | env | journal rows with seq ≤ snapshot_seq − window are compacted away (chat-pattern replay window). | no | 500 |
+| AUTO_REVISION_INTERVAL_SECONDS | env | a snapshot save mints an `auto` Revision when the newest revision is older than this (0 = revision on every save). | no | 300 |
+| FOLDER_MAX_DEPTH | env | folder tree depth ceiling (create/move/ingest-path all enforce it). | no | 10 |
+| TRASH_RETENTION_DAYS | env | soft-deleted items become purgeable by `docs_purge_expired` after this many days; purge is irreversible. | no | 30 |
+
+### Sharing axis (closed defaults; v1 system-check guards E010-E014) (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| SHARING.MODES | env | additional grant sources over the immutable workspace baseline (subset of whitelist \| link). v1 implements neither — non-empty is a system-check ERROR. | no | [] |
+| SHARING.RESOLVERS | env | {ref_kind: dotted-path} whitelist subject-reference resolvers — real-but-empty seam; entries are import-validated at check time (E014). | no | {} |
+| SHARING.LINK.ANONYMOUS | env | anonymous link redemption. True in v1 = system-check ERROR (E012). | no | false |
+| SHARING.LINK.MAX_LEVEL | env | ceiling for minted link level. Above `view` in v1 = system-check ERROR (E013); `manage` is never grantable by any share source. | no | view |
+| SHARING.LINK.TTL_DAYS | env | link TTL; None (perpetual) only ever by explicit host choice. | no | 30 |

stapel_docs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stapel contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stapel_docs-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: stapel-docs
+Version: 0.1.0
+Summary: Documents: storage, revisions and per-type editors for the Stapel framework
+License: MIT
+Project-URL: Homepage, https://github.com/usestapel/stapel-docs
+Project-URL: Repository, https://github.com/usestapel/stapel-docs
+Project-URL: Documentation, https://github.com/usestapel/stapel-docs#readme
+Project-URL: Changelog, https://github.com/usestapel/stapel-docs/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/usestapel/stapel-docs/issues
+Keywords: django,stapel,docs
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: stapel-core<0.4,>=0.3.0
+Provides-Extra: s3
+Requires-Dist: boto3>=1.26; extra == "s3"
+Provides-Extra: pdf
+Requires-Dist: fpdf2>=2.8; extra == "pdf"
+Provides-Extra: all
+Requires-Dist: boto3>=1.26; extra == "all"
+Requires-Dist: fpdf2>=2.8; extra == "all"
+Dynamic: license-file
+
+<!-- Generated by stapel-readme from docs/readme.md + docs/*.json. Do not edit this file; edit docs/readme.md and re-run `make readme`. -->
+
+# stapel-docs
+
+[![CI](https://img.shields.io/github/actions/workflow/status/usestapel/stapel-docs/ci.yml?branch=main&logo=github&label=CI)](https://github.com/usestapel/stapel-docs/actions/workflows/ci.yml?query=branch%3Amain)
+[![coverage](https://img.shields.io/codecov/c/github/usestapel/stapel-docs?branch=main&logo=codecov&label=coverage)](https://app.codecov.io/gh/usestapel/stapel-docs)
+[![pypi](https://img.shields.io/pypi/v/stapel-docs?logo=pypi&logoColor=white&label=pypi)](https://pypi.org/project/stapel-docs/)
+[![downloads](https://static.pepy.tech/badge/stapel-docs/month)](https://pepy.tech/project/stapel-docs)
+[![python](https://img.shields.io/pypi/pyversions/stapel-docs?logo=python&logoColor=white)](https://pypi.org/project/stapel-docs/)
+[![license](https://img.shields.io/github/license/usestapel/stapel-docs)](https://github.com/usestapel/stapel-docs/blob/main/LICENSE)
+[![llms.txt](https://img.shields.io/badge/llms.txt-blue)](https://github.com/usestapel/stapel-docs/blob/main/docs/llms.txt)
+
+> Google-Drive-style workspace documents: a folder tree, one-entity-per-type documents over an open type registry, content-addressed snapshot storage with an update journal and revision history, optimistic-lock editing (v1), trash with irreversible purge, a swappable object-storage seam, comm ingest (docs.create_document) and registry-driven export (PDF built in).
+
+Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps that deploy as a monolith or as microservices without changing module code.
+
+## Install
+
+```bash
+pip install stapel-docs
+```
+
+## At a glance
+
+| Fact | Value |
+|---|---|
+| Version | `0.1.0` |
+| Python | `>=3.11` (3.11, 3.12, 3.13) |
+| HTTP operations | 27 |
+| Config axes | 1 |
+| Usage surface | 47 |
+| Extension points | 7 |
+| Error codes | 60 |
+| Fleet dependencies | [`stapel-auth`](https://github.com/usestapel/stapel-auth) (optional) · [`stapel-core`](https://github.com/usestapel/stapel-core) · [`stapel-workspaces`](https://github.com/usestapel/stapel-workspaces) (optional) |
+
+## Documentation
+
+[OpenAPI](https://github.com/usestapel/stapel-docs/blob/main/docs/schema.json) · [capabilities.json](https://github.com/usestapel/stapel-docs/blob/main/docs/capabilities.json) · [llms.txt (for agents)](https://github.com/usestapel/stapel-docs/blob/main/docs/llms.txt)
+
+## What this is
+
+Google-Drive-style **workspace documents**: a folder tree, documents that are
+each ONE entity with a `type` from an open registry (`txt` / `md` / `csv` /
+opaque `file` built in), a journal + revision versioning substrate, trash with
+irreversible purge, and registry-driven export (PDF built in).
+
+The versioning substrate is decided for both collaboration disciplines:
+**snapshot** types save whole states under optimistic lock (`If-Match` carries
+the client's `head_seq` — v1's editing model), **crdt** types accumulate an
+append-only update journal between snapshots with chat-pattern replay/resync.
+Which discipline applies is a property of the *type*, not the request.
+
+Object storage is content-addressed and goes through a swappable seam
+(`STORAGE`); the library is **body-blind** — the storage substrate never
+parses a document body, only a type's own `text_extractor` may.
+
+## Quick start
+
+The base install rides Django's `default_storage`; add extras for the
+boto3 S3/MinIO backend and the PDF exporter:
+
+```bash
+pip install "stapel-docs[s3,pdf]"
+```
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "stapel_docs",
+]
+
+# urls.py
+path("docs/", include("stapel_docs.urls"))   # -> /docs/api/v1/...
+```
+
+Authorization asks the `workspaces.check_capability` comm Function
+(fail-closed, deny-by-default) — install stapel-workspaces or provide that
+Function for any HTTP request to be allowed.
+
+## An open type registry, not an enum
+
+```python
+STAPEL_DOCS = {
+    # Add or replace document types ({slug: dotted-path | None removes}):
+    "DOC_TYPES": {"sheet": "myproject.docs.SHEET_SPEC"},
+    # Add export formats over the built-in pdf:
+    "EXPORTERS": {"docx": "myproject.docs.DocxExporter"},
+    # Event-driven ingest without writing a subscriber:
+    "INGEST": {"meeting.summarized": "myproject.docs.map_summary"},
+    # Swap the object store:
+    "STORAGE": "stapel_docs.storage.S3Backend",
+}
+```
+
+A type whose spec vanishes from the registry degrades to `file` behavior —
+read-only, never unreadable: revisions still list, snapshots still download,
+trash/purge/export still work.
+
+## Ingest
+
+Product glue dumps content in with one comm call — no HTTP, no import:
+
+```python
+call("docs.create_document", {
+    "workspace_id": ws_id, "type": "md", "title": "Weekly sync",
+    "body": summary_text, "folder_path": "/Meetings/2026-08",
+})
+```
+
+`folder_path` materializes folders idempotently; an unknown `type` refuses
+loudly so content never silently lands under a mistyped slug.
+
+## Sharing (v1: closed by default)
+
+The sharing axis (`SHARING`: whitelist / link modes) ships its config surface
+with **closed defaults** — v1 implements exactly the immutable workspace
+baseline, and opening any sharing knob before the mechanism exists is a loud
+system-check error (`stapel_docs.E010-E013`), never a silent no-op.
+
+## Settings
+
+All configuration lives in the `STAPEL_DOCS` namespace (dict setting, flat
+setting, or env var — resolved lazily). Full table in
+[CONFIG.MD](https://github.com/usestapel/stapel-docs/blob/main/CONFIG.MD);
+seam semantics in
+[MODULE.md](https://github.com/usestapel/stapel-docs/blob/main/MODULE.md).
+Highlights: `STORAGE`, `DOC_TYPES`, `EXPORTERS`, `INGEST`, `REPLAY_WINDOW`,
+`AUTO_REVISION_INTERVAL_SECONDS`, `TRASH_RETENTION_DAYS`, `SHARING`.
+
+## comm surface
+
+| Kind | Name | Contract |
+|---|---|---|
+| Function (provides) | `docs.create_document` | `schemas/functions/docs.create_document.json` |
+| Action (emit) | `document.created`, `document.updated`, `document.deleted`, `document.storage_changed` | `schemas/emits/*.json` |
+| Action (consume) | `user.deleted` | GDPR anonymize (authorship nulled, content survives) |
+| Function (call) | `workspaces.check_capability` | provided by stapel-workspaces |
+
+## Operations
+
+```bash
+python manage.py docs_purge_expired   # purge trash older than TRASH_RETENTION_DAYS
+```
+
+## Development
+
+```bash
+pip install -e . && pip install pytest pytest-django ruff jsonschema djangorestframework
+./setup-hooks.sh
+pytest tests/
+```
+
+## License
+
+MIT — see [LICENSE](https://github.com/usestapel/stapel-docs/blob/main/LICENSE).
+
+---
+
+<sub>This page is assembled by `stapel-readme` from `docs/readme.md` plus the contract artifacts in `docs/`. Edit the prose in `docs/readme.md`; the badges, facts and links above and below it are generated — do not hand-edit `README.md`.</sub>

stapel_docs-0.1.0/README.md

@@ -0,0 +1,159 @@
+<!-- Generated by stapel-readme from docs/readme.md + docs/*.json. Do not edit this file; edit docs/readme.md and re-run `make readme`. -->
+
+# stapel-docs
+
+[![CI](https://img.shields.io/github/actions/workflow/status/usestapel/stapel-docs/ci.yml?branch=main&logo=github&label=CI)](https://github.com/usestapel/stapel-docs/actions/workflows/ci.yml?query=branch%3Amain)
+[![coverage](https://img.shields.io/codecov/c/github/usestapel/stapel-docs?branch=main&logo=codecov&label=coverage)](https://app.codecov.io/gh/usestapel/stapel-docs)
+[![pypi](https://img.shields.io/pypi/v/stapel-docs?logo=pypi&logoColor=white&label=pypi)](https://pypi.org/project/stapel-docs/)
+[![downloads](https://static.pepy.tech/badge/stapel-docs/month)](https://pepy.tech/project/stapel-docs)
+[![python](https://img.shields.io/pypi/pyversions/stapel-docs?logo=python&logoColor=white)](https://pypi.org/project/stapel-docs/)
+[![license](https://img.shields.io/github/license/usestapel/stapel-docs)](https://github.com/usestapel/stapel-docs/blob/main/LICENSE)
+[![llms.txt](https://img.shields.io/badge/llms.txt-blue)](https://github.com/usestapel/stapel-docs/blob/main/docs/llms.txt)
+
+> Google-Drive-style workspace documents: a folder tree, one-entity-per-type documents over an open type registry, content-addressed snapshot storage with an update journal and revision history, optimistic-lock editing (v1), trash with irreversible purge, a swappable object-storage seam, comm ingest (docs.create_document) and registry-driven export (PDF built in).
+
+Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps that deploy as a monolith or as microservices without changing module code.
+
+## Install
+
+```bash
+pip install stapel-docs
+```
+
+## At a glance
+
+| Fact | Value |
+|---|---|
+| Version | `0.1.0` |
+| Python | `>=3.11` (3.11, 3.12, 3.13) |
+| HTTP operations | 27 |
+| Config axes | 1 |
+| Usage surface | 47 |
+| Extension points | 7 |
+| Error codes | 60 |
+| Fleet dependencies | [`stapel-auth`](https://github.com/usestapel/stapel-auth) (optional) · [`stapel-core`](https://github.com/usestapel/stapel-core) · [`stapel-workspaces`](https://github.com/usestapel/stapel-workspaces) (optional) |
+
+## Documentation
+
+[OpenAPI](https://github.com/usestapel/stapel-docs/blob/main/docs/schema.json) · [capabilities.json](https://github.com/usestapel/stapel-docs/blob/main/docs/capabilities.json) · [llms.txt (for agents)](https://github.com/usestapel/stapel-docs/blob/main/docs/llms.txt)
+
+## What this is
+
+Google-Drive-style **workspace documents**: a folder tree, documents that are
+each ONE entity with a `type` from an open registry (`txt` / `md` / `csv` /
+opaque `file` built in), a journal + revision versioning substrate, trash with
+irreversible purge, and registry-driven export (PDF built in).
+
+The versioning substrate is decided for both collaboration disciplines:
+**snapshot** types save whole states under optimistic lock (`If-Match` carries
+the client's `head_seq` — v1's editing model), **crdt** types accumulate an
+append-only update journal between snapshots with chat-pattern replay/resync.
+Which discipline applies is a property of the *type*, not the request.
+
+Object storage is content-addressed and goes through a swappable seam
+(`STORAGE`); the library is **body-blind** — the storage substrate never
+parses a document body, only a type's own `text_extractor` may.
+
+## Quick start
+
+The base install rides Django's `default_storage`; add extras for the
+boto3 S3/MinIO backend and the PDF exporter:
+
+```bash
+pip install "stapel-docs[s3,pdf]"
+```
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "stapel_docs",
+]
+
+# urls.py
+path("docs/", include("stapel_docs.urls"))   # -> /docs/api/v1/...
+```
+
+Authorization asks the `workspaces.check_capability` comm Function
+(fail-closed, deny-by-default) — install stapel-workspaces or provide that
+Function for any HTTP request to be allowed.
+
+## An open type registry, not an enum
+
+```python
+STAPEL_DOCS = {
+    # Add or replace document types ({slug: dotted-path | None removes}):
+    "DOC_TYPES": {"sheet": "myproject.docs.SHEET_SPEC"},
+    # Add export formats over the built-in pdf:
+    "EXPORTERS": {"docx": "myproject.docs.DocxExporter"},
+    # Event-driven ingest without writing a subscriber:
+    "INGEST": {"meeting.summarized": "myproject.docs.map_summary"},
+    # Swap the object store:
+    "STORAGE": "stapel_docs.storage.S3Backend",
+}
+```
+
+A type whose spec vanishes from the registry degrades to `file` behavior —
+read-only, never unreadable: revisions still list, snapshots still download,
+trash/purge/export still work.
+
+## Ingest
+
+Product glue dumps content in with one comm call — no HTTP, no import:
+
+```python
+call("docs.create_document", {
+    "workspace_id": ws_id, "type": "md", "title": "Weekly sync",
+    "body": summary_text, "folder_path": "/Meetings/2026-08",
+})
+```
+
+`folder_path` materializes folders idempotently; an unknown `type` refuses
+loudly so content never silently lands under a mistyped slug.
+
+## Sharing (v1: closed by default)
+
+The sharing axis (`SHARING`: whitelist / link modes) ships its config surface
+with **closed defaults** — v1 implements exactly the immutable workspace
+baseline, and opening any sharing knob before the mechanism exists is a loud
+system-check error (`stapel_docs.E010-E013`), never a silent no-op.
+
+## Settings
+
+All configuration lives in the `STAPEL_DOCS` namespace (dict setting, flat
+setting, or env var — resolved lazily). Full table in
+[CONFIG.MD](https://github.com/usestapel/stapel-docs/blob/main/CONFIG.MD);
+seam semantics in
+[MODULE.md](https://github.com/usestapel/stapel-docs/blob/main/MODULE.md).
+Highlights: `STORAGE`, `DOC_TYPES`, `EXPORTERS`, `INGEST`, `REPLAY_WINDOW`,
+`AUTO_REVISION_INTERVAL_SECONDS`, `TRASH_RETENTION_DAYS`, `SHARING`.
+
+## comm surface
+
+| Kind | Name | Contract |
+|---|---|---|
+| Function (provides) | `docs.create_document` | `schemas/functions/docs.create_document.json` |
+| Action (emit) | `document.created`, `document.updated`, `document.deleted`, `document.storage_changed` | `schemas/emits/*.json` |
+| Action (consume) | `user.deleted` | GDPR anonymize (authorship nulled, content survives) |
+| Function (call) | `workspaces.check_capability` | provided by stapel-workspaces |
+
+## Operations
+
+```bash
+python manage.py docs_purge_expired   # purge trash older than TRASH_RETENTION_DAYS
+```
+
+## Development
+
+```bash
+pip install -e . && pip install pytest pytest-django ruff jsonschema djangorestframework
+./setup-hooks.sh
+pytest tests/
+```
+
+## License
+
+MIT — see [LICENSE](https://github.com/usestapel/stapel-docs/blob/main/LICENSE).
+
+---
+
+<sub>This page is assembled by `stapel-readme` from `docs/readme.md` plus the contract artifacts in `docs/`. Edit the prose in `docs/readme.md`; the badges, facts and links above and below it are generated — do not hand-edit `README.md`.</sub>

stapel_docs-0.1.0/__init__.py

@@ -0,0 +1,31 @@
+"""stapel-docs — Documents: storage, revisions and per-type editors for the Stapel framework.
+
+Public API (lazily exported, PEP 562 — importing this package never pulls
+in Django or requires configured settings):
+
+- ``docs_settings`` — resolved app settings (``stapel_docs.conf``).
+"""
+
+__all__ = [
+    "docs_settings",
+]
+
+# name -> submodule that defines it. Resolution is deferred until first
+# attribute access so that `import stapel_docs` stays Django-free.
+_LAZY_EXPORTS = {
+    "docs_settings": ".conf",
+}
+
+
+def __getattr__(name):
+    if name in _LAZY_EXPORTS:
+        from importlib import import_module
+
+        value = getattr(import_module(_LAZY_EXPORTS[name], __name__), name)
+        globals()[name] = value  # cache for subsequent lookups
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))

stapel_docs-0.1.0/_capabilities.py

@@ -0,0 +1,39 @@
+"""stapel-docs capabilities.json emitter — thin shim over stapel_tools.capabilities."""
+from pathlib import Path
+
+from stapel_tools.capabilities import axis_group_rules, run_capabilities_cli
+
+
+def main(argv=None):
+    from stapel_docs._codegen import _configure
+
+    _configure()
+    from stapel_docs.conf import DEFAULTS
+    from stapel_docs.urls_v1 import GATE_REGISTRY
+
+    # SHARING is the one CTO-facing axis: does the product grant access
+    # beyond the immutable workspace baseline (MODES / LINK.* — closed by
+    # default, v1 system checks E010-E013 refuse opening it before the
+    # mechanism exists). The emitter expresses axes as top-level DEFAULTS
+    # keys only, so the nested MODES/LINK.* knobs surface as ONE composite
+    # SHARING axis (derived kind "enum", default = the closed dict) rather
+    # than per-key axes — honest within the mechanism, detailed in the
+    # curated summary. STORAGE/DOC_TYPES/EXPORTERS/INGEST/SHARING RESOLVERS
+    # are extension seams (curated in docs/capabilities.meta.json);
+    # timeouts, URL lifetimes, REPLAY_WINDOW, AUTO_REVISION_INTERVAL,
+    # FOLDER_MAX_DEPTH, TRASH_RETENTION_DAYS and the S3_* block are tuning
+    # — neither axes nor extension points.
+    return run_capabilities_cli(
+        argv,
+        repo=Path(__file__).resolve().parent,
+        canonical_prefix="/docs/api/v1",
+        defaults=DEFAULTS,
+        registry=GATE_REGISTRY,
+        is_axis=lambda k: k == "SHARING",
+        axis_group=axis_group_rules(exact={"SHARING": "docs.sharing"}),
+        prog="stapel-docs-capabilities",
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

stapel_docs-0.1.0/_codegen.py

@@ -0,0 +1,143 @@
+"""stapel-docs contract-emission harness (contract-pipeline.md §2-3).
+
+Emits the module's own contract triad into ``docs/`` from a single-module
+``{docs + core}`` Django instance mounted at the canonical ``/docs/api/v1``
+prefix:
+
+  docs/schema.json   drf-spectacular OpenAPI, this module only, canonical prefix
+  docs/flows.json    generate_flow_docs machine artifact — empty here, this
+                     module has no ``@flow_step`` annotations
+  docs/errors.json   generate_error_keys registry (the per-module etalon)
+
+Copied from stapel-recordings' adaptation of the stapel-auth reference
+implementation; the *mechanism* is stapel_tools.codegen (unchanged, shared),
+this file is the thin per-module *config* that wires the module's settings +
+canonical mount into it.
+
+Like recordings, stapel-docs is **not mounted in stapel-example-monolith**
+(grep-confirmed: no route for it in ``svc-app/core/urls.py``), so there is no
+monolith aggregate slice to diff this artifact against for byte-identity.
+Validation is standalone instead — see ``tests/test_contract.py``.
+
+Usage:
+    python -m stapel_docs._codegen --out docs        # `make contract`
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+
+def _configure() -> None:
+    """Configure + boot the single-module Django instance for emission."""
+    # `python -m` prepends cwd to sys.path; strip the repo root the same way
+    # a flat-layout conftest does (defensively — docs has no colliding
+    # subpackage today, but the guard costs nothing and keeps the harness
+    # identical in shape to auth/profiles/recordings).
+    repo_root = os.path.dirname(os.path.abspath(__file__))
+    sys.path[:] = [p for p in sys.path if os.path.abspath(p or os.getcwd()) != repo_root]
+
+    from django.conf import settings
+
+    if not settings.configured:
+        from stapel_docs._codegen_settings import settings_kwargs
+
+        settings.configure(
+            **settings_kwargs(root_urlconf="stapel_docs.codegen_urls", contract=True)
+        )
+
+    import django
+
+    django.setup()
+
+    # drf-spectacular froze its settings singleton at import time (before this
+    # harness ran configure()), so it is on drf defaults — the same state
+    # every other pair-backend's harness emits under. The one knob to force is
+    # SCHEMA_PATH_PREFIX: left None, drf derives the operationId prefix from
+    # the common path of all endpoints — "/" across a multi-module aggregate
+    # (operationIds keep the mount segment, docs_api_*), but "/docs/api" in a
+    # single-module harness (which would strip it to bare anonymous names).
+    # Pin it to the aggregate convention so the operationIds match every other
+    # module's harness; SCHEMA_PATH_PREFIX_TRIM stays False (default) so the
+    # path *keys* keep /docs/api/v1/ on both sides.
+    from drf_spectacular.settings import spectacular_settings
+
+    from stapel_docs._codegen_settings import CODEGEN_SCHEMA_PATH_PREFIX
+
+    spectacular_settings.SCHEMA_PATH_PREFIX = CODEGEN_SCHEMA_PATH_PREFIX
+
+    # A real all-modules deployment registers drf-spectacular's JWT-cookie
+    # security-scheme extension as a side effect of its own dev-only Swagger
+    # URLs (DJANGO_ENV=local) — a *global* registration on drf-spectacular's
+    # extension registry, not tied to any one module's urls.py. stapel-docs
+    # has no co-mounted sibling to trigger it (the profiles finding —
+    # contract-pipeline.md brief), so without registering it explicitly here,
+    # docs' protected endpoints (every view is
+    # ``permission_classes = [IsNotAnonymousUser]``) would emit without their
+    # `security: [{"JWTCookieAuth": []}]` entry.
+    from stapel_core.django.openapi.swagger import _register_jwt_auth_extension
+
+    _register_jwt_auth_extension()
+
+
+def _require_python_312() -> None:
+    """Abort emission if not running the pinned 3.12 interpreter.
+
+    drf-spectacular's rendering of component descriptions (``Optional[X]`` vs
+    ``X | None``) depends on the Python **minor** version — contracts emitted
+    on anything other than 3.12 (the CI/monolith pin) produce false diffs
+    against the committed docs/*.json. Emission must never proceed on the
+    wrong minor.
+    """
+    if sys.version_info[:2] != (3, 12):
+        got = f"{sys.version_info.major}.{sys.version_info.minor}"
+        raise SystemExit(
+            f"stapel-docs contract emission ABORTED: running Python {got}, "
+            "but contracts must be emitted on Python 3.12 (the CI/monolith "
+            "pin). drf-spectacular renders component descriptions "
+            "(Optional[X] vs X | None) differently across Python minor "
+            "versions, so emitting on any other minor produces false diffs "
+            "against the committed docs/*.json. Re-run under a 3.12 "
+            "interpreter."
+        )
+
+
+def main(argv: list[str] | None = None) -> int:
+    _require_python_312()
+
+    parser = argparse.ArgumentParser(
+        prog="stapel-docs-contract",
+        description="Emit this module's contract triad (schema.json + flows.json "
+        "+ errors.json) into --out, canonical /docs/api/v1 prefix.",
+    )
+    parser.add_argument(
+        "--out",
+        default="docs",
+        help="Output directory for the triad (default: docs).",
+    )
+    args = parser.parse_args(argv)
+
+    _configure()
+
+    # Reuse the shared mechanism's byte-stable emitters (contract-pipeline.md §2:
+    # "the single-module harness already exists").
+    from stapel_tools.codegen import emit_errors, emit_flows, emit_schema
+
+    out = Path(args.out)
+    out.mkdir(parents=True, exist_ok=True)
+    paths = emit_schema(out / "schema.json")
+    flows = emit_flows(out / "flows.json")
+    errors = emit_errors(out / "errors.json")
+
+    print(
+        f"stapel-docs contract: {paths} paths, {flows} flows, {errors} error keys "
+        f"→ {out}/",
+        file=sys.stderr,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())