pubkit 0.1.0__py3-none-any.whl

pubkit/scaffold.py

@@ -0,0 +1,271 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0
+"""`pubkit init` and `pubkit doctor`.
+
+Adoption is mostly a first-five-minutes problem. `init` gives someone a content
+repo that already validates and already has a working CI pipeline; `doctor`
+answers "why isn't this working" without them having to read the source.
+"""
+from __future__ import annotations
+
+import importlib.util
+import os
+import platform
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+SAMPLE_POST = '''---
+id: hello-world
+title: "The thing I learned the hard way"
+subtitle: A one-line promise of what the reader gets.
+tags: [Engineering, Writing]
+canonical_url: ""
+# Uncomment to have the build check your length:
+# budget: {words: 1200, tolerance: 0.15}
+---
+
+# What this is about
+
+Open with the specific, surprising fact. Not a preamble — the fact.
+
+Numbers you will reuse can be declared once and checked by the build:
+
+<!-- pubkit:define fast = 900 -->
+<!-- pubkit:define slow = 128 -->
+
+The fast path is 7× wider than the slow one. <!-- pubkit:assert 7x = fast/slow ±10% -->
+
+## A section with evidence
+
+| Approach | Throughput |
+| :--- | ---: |
+| Naive | 128 MB/s |
+| Tuned | 900 MB/s |
+*Measured on the same hardware, same dataset*
+
+> [!key] The rule
+> State the rule you want the reader to remember, once, in its own block.
+
+```python
+def example() -> None:
+    print("code blocks survive to every platform that supports them")
+```
+
+Close with what changes for the reader tomorrow.
+'''
+
+SAMPLE_SERIES_NOTE = '''---
+id: part-1
+title: "My Series, Part 1: The Setup"
+subtitle: What part one establishes.
+tags: [Engineering]
+series: {id: my-series, index: 1, of: 2}
+---
+
+# The first idea
+
+Cross-links resolve themselves during a two-phase publish:
+
+Continued in [Part 2](${series.part2.url}).
+'''
+
+CONFIG = """# pubkit.toml — optional. Everything here can also be a CLI flag.
+[defaults]
+platforms = ["medium", "devto"]
+
+[medium]
+# Medium has no tables; pubkit renders yours as styled images automatically.
+
+[devto]
+# Dev.to wants images at public URLs. Point this at wherever you host them.
+# asset_base_url = "https://raw.githubusercontent.com/you/blog/main/"
+
+[x]
+mode = "promo"        # "promo" (hook + claims + link) or "full"
+max_posts = 12
+"""
+
+CI = """name: publish
+on:
+  pull_request:
+    paths: ["content/**"]
+  push:
+    branches: [main]
+    paths: ["content/**"]
+
+jobs:
+  plan:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: {python-version: "3.12"}
+      - run: pip install "pubkit[all]"
+      - run: pubkit validate content/ --strict
+      - name: Plan
+        run: |
+          echo '## Publishing plan' >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          pubkit plan content/ --to medium,devto >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+
+  publish:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment: production   # add a required reviewer here for a human gate
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: {python-version: "3.12"}
+      - run: pip install "pubkit[all]"
+      - run: pubkit publish content/ --to devto --confirm
+        env:
+          PUBKIT_DEVTO_TOKEN: ${{ secrets.DEVTO_TOKEN }}
+"""
+
+README = """# Content
+
+Written once here, published everywhere by [pubkit](https://github.com/arunsingh/pubkit).
+
+```bash
+pubkit validate content/            # check before anything leaves your laptop
+pubkit plan content/ --to medium    # see exactly what the platform will get
+pubkit publish content/ --to medium # draft
+pubkit publish content/ --to medium --confirm   # live
+```
+
+`.pubkit/` holds the state store and your encrypted sessions. It is gitignored,
+and it is what makes a re-run resume instead of duplicating your drafts.
+"""
+
+
+def init_repo(root: Path, *, series: bool = False, force: bool = False) -> list[Path]:
+    """Scaffold a content repository that validates on the first try."""
+    written: list[Path] = []
+
+    def write(rel: str, text: str) -> None:
+        p = root / rel
+        if p.exists() and not force:
+            return
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(text, encoding="utf-8")
+        written.append(p)
+
+    write("content/hello-world.md", SAMPLE_POST)
+    if series:
+        write("content/series/part-1.md", SAMPLE_SERIES_NOTE)
+        write(
+            "content/series/part-2.md",
+            SAMPLE_SERIES_NOTE.replace("part-1", "part-2")
+            .replace("index: 1", "index: 2")
+            .replace("Part 1: The Setup", "Part 2: The Payoff")
+            .replace("What part one establishes.", "What part two delivers.")
+            .replace("Continued in [Part 2](${series.part2.url}).", "Back to [Part 1](${series.part1.url})."),
+        )
+    write("content/img/.gitkeep", "")
+    write("pubkit.toml", CONFIG)
+    write(".github/workflows/publish.yml", CI)
+    write("README.md", README)
+    write(".gitignore", ".pubkit/\n__pycache__/\n")
+    return written
+
+
+# ---------------------------------------------------------------------------
+# doctor
+# ---------------------------------------------------------------------------
+@dataclass
+class Finding:
+    ok: bool
+    label: str
+    detail: str
+    fix: str = ""
+
+
+def _has(mod: str) -> bool:
+    return importlib.util.find_spec(mod) is not None
+
+
+def diagnose() -> list[Finding]:
+    """Answer 'why isn't this working' before anyone has to read the source."""
+    out: list[Finding] = []
+
+    v = sys.version_info
+    out.append(
+        Finding(
+            v >= (3, 11),
+            "python",
+            f"{v.major}.{v.minor}.{v.micro} on {platform.system()}",
+            "pubkit needs Python 3.11+",
+        )
+    )
+
+    out.append(
+        Finding(
+            _has("playwright"),
+            "playwright",
+            "installed" if _has("playwright") else "missing",
+            'pip install "pubkit[browser]" && playwright install chromium '
+            "— required for Medium and Substack only",
+        )
+    )
+
+    if _has("playwright"):
+        from pathlib import Path as _P
+
+        cache = _P.home() / (
+            "Library/Caches/ms-playwright" if platform.system() == "Darwin" else ".cache/ms-playwright"
+        )
+        found = cache.exists() and any(cache.glob("chromium*"))
+        out.append(
+            Finding(found, "chromium", "downloaded" if found else "not downloaded", "playwright install chromium")
+        )
+
+    out.append(
+        Finding(
+            _has("keyring"),
+            "keyring",
+            "available — tokens go to the OS keychain" if _has("keyring") else "missing",
+            'pip install "pubkit[keychain]", or set PUBKIT_VAULT_KEY for an encrypted file vault',
+        )
+    )
+    out.append(
+        Finding(
+            _has("cryptography"),
+            "cryptography",
+            "available — sessions encrypted at rest" if _has("cryptography") else "missing",
+            'pip install "pubkit[keychain]" — without it, saved sessions are stored in plain text',
+        )
+    )
+
+    state = Path(".pubkit/state.sqlite")
+    out.append(
+        Finding(
+            True,
+            "state store",
+            f"{state} ({state.stat().st_size} bytes)" if state.exists() else "not created yet (normal)",
+        )
+    )
+
+    from .core.auth import SessionStore, TokenStore
+    from .registry import list_adapters
+
+    tokens, sessions = TokenStore(), SessionStore()
+    for name, _ in list_adapters():
+        has_tok = bool(tokens.get(name)) or bool(tokens.get(name, "bearer"))
+        has_sess = sessions.exists(name)
+        out.append(
+            Finding(
+                has_tok or has_sess,
+                f"auth:{name}",
+                "token" if has_tok else "session" if has_sess else "not configured",
+                f"pubkit auth login {name}",
+            )
+        )
+
+    env = [k for k in os.environ if k.startswith("PUBKIT_")]
+    if env:
+        out.append(Finding(True, "env", ", ".join(sorted(env))))
+
+    return out

pubkit/workflows/__init__.py

@@ -0,0 +1,2 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0

pubkit/workflows/airflow.py

@@ -0,0 +1,115 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0
+"""Airflow integration.
+
+One task per (document, platform) rather than one task for the whole fan-out.
+That is the entire trick: retries, alerting, SLA misses and partial reruns
+become Airflow's problem, which it is much better at than a bespoke loop.
+
+    with DAG("blog", schedule="0 9 * * TUE") as dag:
+        validate = PubkitValidateOperator(task_id="validate", path="content/series/")
+        fanout = PubkitPublishOperator.expand_fanout(
+            path="content/series/",
+            platforms=["medium", "devto", "x"],
+            confirm=True,
+        )
+        validate >> fanout
+"""
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+try:  # pragma: no cover - optional dependency
+    from airflow.exceptions import AirflowFailException
+    from airflow.models import BaseOperator
+except Exception:  # pragma: no cover
+    BaseOperator = object  # type: ignore[assignment,misc]
+
+    class AirflowFailException(RuntimeError):  # type: ignore[no-redef]
+        pass
+
+
+class PubkitValidateOperator(BaseOperator):  # type: ignore[misc]
+    """Run the check pipeline. Fails the DAG before anything reaches a platform."""
+
+    template_fields = ("path",)
+
+    def __init__(self, path: str, strict: bool = False, **kw: Any) -> None:
+        super().__init__(**kw)
+        self.path, self.strict = path, strict
+
+    def execute(self, context) -> dict:
+        from ..core.checks import run_checks
+        from ..core.loader import load_document, load_series
+
+        p = Path(self.path)
+        docs = load_series(sorted(p.glob("*.md"))).documents if p.is_dir() else [load_document(p)]
+        problems = []
+        for doc in docs:
+            res = run_checks(doc)
+            for f in res.findings:
+                self.log.info("%s", f)
+            if res.errors or (self.strict and res.findings):
+                problems.append(doc.id)
+        if problems:
+            raise AirflowFailException(f"checks failed for: {', '.join(problems)}")
+        return {"documents": [d.id for d in docs]}
+
+
+class PubkitPublishOperator(BaseOperator):  # type: ignore[misc]
+    """Publish one document to one platform.
+
+    Idempotent by construction: the state store means an Airflow retry resumes
+    at the failed step rather than starting over, and never creates a second
+    draft.
+    """
+
+    template_fields = ("path", "platform")
+
+    def __init__(
+        self,
+        path: str,
+        platform: str,
+        document_id: str | None = None,
+        confirm: bool = False,
+        state_path: str = ".pubkit/state.sqlite",
+        **kw: Any,
+    ) -> None:
+        super().__init__(**kw)
+        self.path, self.platform = path, platform
+        self.document_id, self.confirm, self.state_path = document_id, confirm, state_path
+
+    def execute(self, context) -> dict:
+        from ..core.adapter import Context
+        from ..core.auth import SessionStore, TokenStore
+        from ..core.loader import load_document, load_series
+        from ..core.runner import Pipeline
+        from ..core.state import StateStore
+        from ..registry import build_adapter
+
+        p = Path(self.path)
+        docs = load_series(sorted(p.glob("*.md"))).documents if p.is_dir() else [load_document(p)]
+        if self.document_id:
+            docs = [d for d in docs if d.id == self.document_id]
+
+        tokens, sessions = TokenStore(), SessionStore()
+        adapter = build_adapter(self.platform)
+        pipe = Pipeline(StateStore(self.state_path))
+
+        def ctx_for(_name: str) -> Context:
+            return Context(platform=self.platform, tokens=tokens, sessions=sessions, confirm=self.confirm)
+
+        # A stable run_id per DAG run is what makes an Airflow retry resume
+        # instead of restart.
+        run_id = f"airflow-{context['run_id']}"
+        report = asyncio.run(pipe.run(docs, [adapter], ctx_for, publish=self.confirm, run_id=run_id))
+        if not report.ok:
+            raise AirflowFailException(report.human())
+        return {"legs": [leg.__dict__ for leg in report.legs]}
+
+    @classmethod
+    def expand_fanout(cls, path: str, platforms: Sequence[str], **kw: Any) -> list:
+        return [cls(task_id=f"publish_{p}", path=path, platform=p, **kw) for p in platforms]

pubkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,291 @@
+Metadata-Version: 2.5
+Name: pubkit
+Version: 0.1.0
+Summary: Publish one source to many platforms, safely. Medium, Substack, X, Dev.to, Hashnode.
+Project-URL: Homepage, https://github.com/arunsingh/pubkit
+Project-URL: Issues, https://github.com/arunsingh/pubkit/issues
+Project-URL: Documentation, https://github.com/arunsingh/pubkit#readme
+Project-URL: Changelog, https://github.com/arunsingh/pubkit/blob/main/CHANGELOG.md
+Project-URL: Failure modes, https://github.com/arunsingh/pubkit/blob/main/docs/FAILURE-MODES.md
+Author: Arun Singh
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: automation,content,devto,hashnode,medium,publishing,substack,twitter,x
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: airflow
+Requires-Dist: apache-airflow>=2.9; extra == 'airflow'
+Provides-Extra: all
+Requires-Dist: cryptography>=42.0; extra == 'all'
+Requires-Dist: keyring>=25.0; extra == 'all'
+Requires-Dist: pillow>=10.0; extra == 'all'
+Requires-Dist: playwright>=1.44; extra == 'all'
+Provides-Extra: browser
+Requires-Dist: playwright>=1.44; extra == 'browser'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: keychain
+Requires-Dist: cryptography>=42.0; extra == 'keychain'
+Requires-Dist: keyring>=25.0; extra == 'keychain'
+Provides-Extra: render
+Requires-Dist: pillow>=10.0; extra == 'render'
+Description-Content-Type: text/markdown
+
+# pubkit
+
+**Publish one source to many platforms, safely.**
+Medium · Substack · X · Dev.to · Hashnode — and whatever you add next.
+
+[![PyPI](https://img.shields.io/pypi/v/pubkit.svg)](https://pypi.org/project/pubkit/)
+[![Python](https://img.shields.io/pypi/pyversions/pubkit.svg)](https://pypi.org/project/pubkit/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![CI](https://github.com/arunsingh/pubkit/actions/workflows/ci.yml/badge.svg)](https://github.com/arunsingh/pubkit/actions/workflows/ci.yml)
+
+---
+
+## Why this exists
+
+I published a 15,000-word, three-part illustrated series to Medium. It took far
+longer than writing it, and not for any reason I could have predicted.
+
+A 12,368-character payload arrived with exactly **one byte** changed, and
+nothing reported an error. Pasting a document replaced 2 of 169 paragraphs and
+silently appended the rest, producing a scrambled duplicate. A delete that
+visibly worked was back after a reload. Link hrefs set in the DOM reverted every
+time. Every image — `data:` URI and `https://` URL alike — was stripped out of
+pasted HTML, and it took eight dead ends to find the one insertion path that
+works. A scripted check of 32 numeric claims found 5 that were wrong, including
+two ratios transposed in an edit that no amount of re-reading had caught. And
+the automation bridge dropped eight times, so everything had to be re-runnable.
+
+None of that is Medium being unusual. It is what automating *any* rich-text
+editor looks like. pubkit is that knowledge, extracted and made reusable.
+
+[`docs/FAILURE-MODES.md`](docs/FAILURE-MODES.md) catalogues all of it — every
+entry names the component that answers it.
+
+## Install
+
+```bash
+pip install "pubkit[all]"
+playwright install chromium     # Medium and Substack only
+pubkit doctor                   # confirms your environment before you start
+```
+
+Thirty seconds to something real:
+
+```bash
+pubkit init my-blog && cd my-blog
+pubkit validate content/
+pubkit plan content/ --to medium,devto
+```
+
+## Use it
+
+```bash
+# 0. Scaffold a content repo that validates on the first try.
+pubkit init my-blog && cd my-blog
+
+# 1. Check the content. No network, no browser, no side effects.
+pubkit validate content/series/
+
+# 2. See exactly what each platform will get — including every degradation.
+pubkit plan content/series/ --to medium,devto,x
+
+# 3. Sign in. pubkit never accepts a password.
+pubkit auth login medium        # opens a window; you sign in; it keeps the session
+pubkit auth login devto         # API token → OS keychain
+
+# 4. Drafts everywhere. Safe to re-run; a dropped connection costs one step.
+pubkit publish content/series/ --to medium,devto,x
+
+# 5. Go live.
+pubkit publish content/series/ --to medium,devto,x --confirm
+```
+
+`plan` output on a real series:
+
+```
+medium: part-1 (bf9abfe78ce4)
+  · images_via_browser   4 image(s) uploaded through the editor's own paste path
+                         — remote URLs and data: URIs are stripped by this platform
+  · code_flattened       4 code block(s) lose syntax highlighting
+
+devto: part-1 (bf9abfe78ce4)
+  · tags_trimmed         keeping 4 of 5
+
+x: part-1 (bf9abfe78ce4)
+  · split_into_thread    promo thread: 12 posts — hook, key claims, link to the full article
+  · tags_trimmed         5 tag(s) dropped — platform has no tags
+```
+
+Nothing is a surprise at publish time. That is the whole design goal.
+
+## Write once
+
+````markdown
+---
+id: part-1
+title: "Inside AI Infrastructure, Part 1: The Hardware"
+subtitle: Why a GPU is fast, and why it turns out to be a memory problem.
+tags: [AI Infrastructure, GPU, SRE]
+series: {id: inside-ai, index: 1, of: 3}
+budget: {words: 3500}
+---
+
+# What is behind the box you type into
+
+<!-- pubkit:define nvlink = 900 -->
+<!-- pubkit:define pcie5 = 128 -->
+
+NVLink is 7× wider than PCIe Gen5. <!-- pubkit:assert 7x = nvlink/pcie5 ±10% -->
+
+| Model | FP16 size |
+| :--- | ---: |
+| 70B  | 140 GB |
+*What the weights actually cost*
+
+![memory layout](img/vram.gif)
+*Every token costs one full read of the model out of VRAM.*
+
+Continued in [Part 2](${series.part2.url}).
+````
+
+That one file becomes: a Medium draft with the table rendered as a styled image
+and the GIF uploaded through the editor's own path; a Dev.to article with a
+native table and a fenced code block; a 12-post promo thread on X with a link
+back. The cross-link resolves itself during a two-phase publish.
+
+## What it actually guards against
+
+| Guard | What it prevents |
+|---|---|
+| Hash-verified chunked transport | a silently corrupted payload |
+| Probed chunk ceiling | undocumented per-call size limits |
+| `replace_document()` with a block-count assert | a paste that appends instead of replacing |
+| Reload-then-fingerprint verification | edits the editor showed you but never saved |
+| Caption-anchored `File` paste | images stripped out of pasted HTML |
+| Unicode-folding anchor resolution | an em dash breaking a text match |
+| Tag-chip post-condition | one 40-character invalid tag instead of five good ones |
+| `pubkit:assert` arithmetic | a transposed ratio reaching print |
+| Two-phase series publish | `URL-PART-2` going live as a link |
+| Content-addressed state store | a re-run creating a second draft |
+| Plan hash + `--confirm` | publishing something other than what you reviewed |
+
+## Architecture in one paragraph
+
+A canonical **Post IR** sits between your source and every platform. Adapters
+declare **capabilities**; the planner intersects the two and emits explicit
+**degradations**. A **runner** executes six steps per (document, platform) —
+auth, draft, content, media, verify, publish — recording each in a sqlite state
+store so a re-run resumes rather than restarts. Browser adapters inherit a DOM
+toolkit that encodes everything above; API adapters inherit rate limiting and
+retries. [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) has the diagram.
+
+## Add a platform
+
+```python
+from pubkit.core.browser import BrowserAdapter, EditorSelectors
+from pubkit.core.capabilities import Capabilities
+
+class GhostAdapter(BrowserAdapter):
+    name = "ghost"
+    capabilities = Capabilities(tables=True, image_upload="browser_paste")
+    selectors = EditorSelectors(
+        editable=".koenig-editor__editor",
+        content_roots=".koenig-editor__editor",   # ALL roots, not the first
+        block="[data-kg='editor'] > *",
+        figure="figure", figure_img="figure img", link="a",
+        publish_button=".gh-publishmenu-trigger",
+    )
+    async def ensure_draft(self, doc, ctx): ...
+    async def publish(self, doc, ref, ctx): ...
+```
+
+Register it from your own package — no fork required:
+
+```toml
+[project.entry-points."pubkit.adapters"]
+ghost = "my_pubkit_ghost:GhostAdapter"
+```
+
+Five extension points, all first-class: `pubkit.adapters`, `pubkit.renderers`,
+`pubkit.checks`, `pubkit.hooks`, and per-platform `transforms:` in config.
+
+## Fit it into a workflow
+
+**GitHub Actions** — plan on every PR, publish on merge:
+
+```yaml
+- run: pubkit validate content/ --strict
+- run: pubkit plan content/ --to medium,devto >> $GITHUB_STEP_SUMMARY
+- run: pubkit publish content/ --to medium,devto --confirm
+  if: github.ref == 'refs/heads/main'
+  env:
+    PUBKIT_VAULT_KEY: ${{ secrets.PUBKIT_VAULT_KEY }}
+```
+
+**Airflow** — one task per (document, platform), so retries and alerting belong
+to Airflow:
+
+```python
+validate = PubkitValidateOperator(task_id="validate", path="content/series/")
+validate >> PubkitPublishOperator.expand_fanout(
+    path="content/series/", platforms=["medium", "devto", "x"], confirm=True,
+)
+```
+
+**Library** — `from pubkit import Pipeline` for everything else.
+
+## Security
+
+- **pubkit never accepts a password.** Browser platforms use an interactive
+  login you perform; pubkit persists only the session, encrypted at rest.
+- API tokens live in the OS keychain, or an encrypted vault for CI.
+- Secrets are stripped from logs by a filter, not by discipline.
+- Adapters receive credentials for their own platform and nothing else.
+- Every public write needs `--confirm`, against a hash-pinned plan.
+
+## Status
+
+v0.1. The core, the checks, the planner and the state machine are tested (32
+tests) and exercised end-to-end against a real published series in
+`examples/inside-ai-infra/`. The browser adapters encode techniques verified by
+hand against live editors; selectors are the part most likely to need a patch
+when a platform ships a redesign, which is exactly why they are isolated in one
+dataclass per adapter.
+
+## Docs
+
+| | |
+|---|---|
+| [QUICKSTART.md](docs/QUICKSTART.md) | five minutes, one platform |
+| [FAILURE-MODES.md](docs/FAILURE-MODES.md) | the 21 ways publishing quietly goes wrong |
+| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | how it fits together |
+| [ADAPTERS.md](docs/ADAPTERS.md) | add a platform |
+| [SECURITY.md](SECURITY.md) | threat model and credential handling |
+
+Contributions welcome — especially new adapters and new checks. The one hard
+rule: a bug fix adds a row to `docs/FAILURE-MODES.md` and a test named after the
+failure. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Licence
+
+Apache 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).