docs: add the brand assets — social preview card, mark, and their generator

[jothimani-rajendran]

What this changes

agentseam has no social preview, so every link to it — GitHub, Slack, a search result, a
post — renders as a bare grey card with the repo name. This adds the same asset set chock
carries, in the same brand:

File	What it is
docs/assets/social-preview.png	1280×640, GitHub's social-preview size, for Settings → Social preview
docs/assets/social-preview.svg	its source
docs/assets/logo.svg, logo-512.png	the mark; the SVG is now in the README header
docs/assets/gen_brand_assets.py	the generator that produces all four

The figure is the claim. Unevenly spaced vendor hook dialects converge through a
stitched seam into one evenly spaced canonical envelope — twelve lines, one per adapter in
src/agentseam/adapters/, which is also what the card's 12 ADAPTERS says and what
matrix_data.py has rows for (both verified at 12 on main).

Two invariants keep the drawing from saying something the project does not do, and the
generator asserts both at render time rather than trusting the eye:

• Nothing crosses. agentseam normalizes the shape of a dialect; it does not reorder
  anything. Crossing lines would claim otherwise.
• Every pair converges — each gap on the dialect side is wider than the matching gap on
  the envelope side. A pair that spread apart would read as fan-out, the opposite of what the
  layer does.

Both were real defects in earlier drafts of this figure, which is why they are now assertions
in the code instead of notes in a comment.

cairosvg is asset tooling a maintainer runs by hand when the artwork changes. It is not
a dependency: the runtime path stays stdlib-only and dependencies = [] in pyproject.toml
is untouched.

Alt text on both images describes the image rather than naming the file — search crawlers and
assistive readers both consume alt text as content, so it carries the canonical sentence.

Claim check

Not applicable to the matrix — no adapter, MATRIX row, or capability claim is touched.

The one factual claim the artwork makes is the adapter count, and it is verified: 12 adapter
modules in src/agentseam/adapters/ (excluding __init__.py and the _windows.py helper)
and 12 rows in matrix_data.py, both counted at main.

Checks

• ruff check . — All checks passed
• ruff format --check . — 88 files already formatted
• Runtime path is still stdlib-only — the diff adds no import to src/; cairosvg is
  imported only by the asset script under docs/
• pytest -q — not re-run; no file under src/ or tests/ is touched by this diff
• Commit is signed off

Also verified: re-running the generator after its refactor reproduces social-preview.png and
logo-512.png byte-for-byte against the renders reviewed before the refactor, so the
committed images provably match the committed source.

Notes for the reviewer

• The PNG in the repo does not set the preview by itself. GitHub's social preview is a
  Settings upload, not a file reference. After merge, upload
  docs/assets/social-preview.png under Settings → General → Social preview.
• The README <img> uses an absolute raw.githubusercontent.com URL (matching chock) because
  the README is also the PyPI long description, where relative paths do not resolve. It will
  render as a broken image to anyone without repo access until the repo goes public — which is
  the next step in the go-live sequence anyway.
• Worth landing before the repo flips public, so the first people who see the link see the card.
• CI on this PR is expected red for the known private-repo Actions ceiling, not for anything in
  the diff. Per contract decision feat(adapters): Grok and Antigravity, and a degradation that was reporting the wrong cause #10, merge manually on the validation above.

---

Generated by Claude Code

[jothimani-rajendran]

CI is red on all 11 checks, and none of it is this PR's

Failing on 423815d: lint, stdlib-only, no-private-data, examples, dco,
test (ubuntu-latest, 3.9), test (3.11), test (3.13), actionlint, semgrep, zizmor.

Same cause as #81: the Actions-minutes
ceiling recorded as contract decision #10. Verified against primary sources rather than assumed:

1. The base branch is red too. CI run #190 on main at c8bd4c4 failed in 5 seconds
   (02:27:19Z → 02:27:24Z), as did #186 and #184. The last green run was #181 at 2026-08-29
   20:54:17Z and took 38 seconds; everything after 20:59:55Z dies in about five.
2. No runner was allocated. This run's dco job reports runner_id: 0, empty
   runner_name, created 02:55:52Z and completed 02:55:54Z. The whole 13-job run was created at
   02:55:51Z and finished at 02:55:57Z — six seconds for everything.
3. Job logs 404. No log exists, because no job body ran.
4. dco cannot fail on this commit. 423815d carries Signed-off-by:.

No re-run, deliberately — decision #10 says nobody re-runs or works around this, and three
attempts were already spent characterizing it on #78.

The fix is the next step in the go-live sequence: flip this repo public. Public repos get
unmetered Actions, which is precisely why the sequence puts the public flip before the tag.

Local validation, covering what this diff can actually break:

• ruff check . → All checks passed; ruff format --check . → 88 files already formatted
• no import added under src/; cairosvg is imported only by the script under docs/
• re-running the generator after its refactor reproduces social-preview.png and
  logo-512.png byte-for-byte, so the committed images provably match the committed source
• the 12 ADAPTERS claim on the card checks out: 12 modules in src/agentseam/adapters/ and
  12 rows in matrix_data.py

One reviewer note worth repeating here, because merging alone does not finish it: GitHub's
social preview is a Settings upload, not a file reference. After merge, upload
docs/assets/social-preview.png under Settings → General → Social preview, ideally in the
same sitting as the public flip so the first links to this repo render with the card.

---

Generated by Claude Code

[jothimani-rajendran]

Social preview rebuilt around real content (aeee10f)

The first card was an abstract line figure plus the tagline. It looked fine and said almost
nothing — someone seeing the link preview learned the positioning sentence and no more. It now
leads with what agentseam actually contains, which is also what a reader is deciding on:

• ADAPTERS · 12 — every adapter by name
• EVENTS · 12 — every normalized event by name
• DECISIONS · 4 — allow, deny, ask, vouch
• ENFORCEMENT · 5 — enforced, enforceable, best-effort, detect, none
• the whole public entry point as two lines of real code, and a footer of counts

Every fact is read from the package at render time. Adapter names from
adapted_agents(); event names cross-checked against EVENTS (a mismatch raises); decision
outcomes probed off Decision; version from __version__; the Python range from
requires-python, with the classifiers as a cross-check. Each count printed beside a list is
len() of that list. There is no independent copy of the truth for the card to drift from.

Where a fact cannot be derived it is not asserted: this branch does not carry
#81's per-version classifiers, so the
footer reads PYTHON 3.9+ rather than inventing a ceiling. Once #81 merges it derives
PYTHON 3.9–3.13; I'll re-render and push that here so the committed PNG matches.

One real error caught while building it

The column headed ENFORCEMENT was listing matrix_terms.TIER_* — block+rewrite,
block, observe, unadapted, none. That is the coverage vocabulary: what an adapter
can serve. The enforcement vocabulary is enforcement_level()'s — enforced, enforceable,
best-effort, detect, none — the honest word a consumer may claim, and the one chock
adopted under contract decision #9. Two different five-word sets, and putting one under the
other's heading would have shipped a quiet false claim on the most-shared image this project
has. The reason they are distinct is now a comment beside the constant.

That is the argument for deriving the rest: this was the one fact I typed by hand, and it was
the one that was wrong.

Verification

• ruff check . → All checks passed; ruff format --check . → 88 files already formatted
• rendering twice produces byte-identical output
• logo-512.png is byte-identical to 423815d — the mark did not change, and the header
  badge reuses the same seam geometry at three lines so it stays legible small. The logo.svg
  diff is element ordering only, which the identical PNG proves
• the seam's two invariants are still assertions, not comments: nothing crosses, every pair
  converges

CI is red for the ceiling, unchanged — see the comment above.

---

Generated by Claude Code