face-lift: README restructure, conventions, ledger, check-knowledge harness, lint CI

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,16 @@
+## What changed
+
+<!-- one paragraph, plain words; say whether any connector-managed file was touched -->
+
+## How it was verified
+
+<!-- paste `python3 harness/check-knowledge.py` and markdownlint output -->
+
+```text
+```
+
+## Where the risk lives
+
+## Ledger
+
+- [ ] Row added to `LEDGER.md`

.github/workflows/lint.yml

@@ -0,0 +1,31 @@
+name: Lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  markdown:
+    name: markdownlint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npx --yes markdownlint-cli2@0.23.3 "**/*.md" "#node_modules"
+
+  knowledge:
+    name: check-knowledge.py
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python3 harness/check-knowledge.py

.gitignore

@@ -0,0 +1,24 @@
+# Secrets and local config — never commit
+.env
+.env.*
+*.pem
+*.key
+secrets/
+
+# OS and editor noise
+.DS_Store
+Thumbs.db
+*.swp
+*~
+.idea/
+.vscode/
+
+# Toolchains
+node_modules/
+__pycache__/
+*.pyc
+.venv/
+
+# Harness output (paste into the PR, do not commit)
+harness/out/
+*.log

.markdownlint.yml

@@ -0,0 +1,8 @@
+# markdownlint-cli2 config. Kept lenient where GitHub renders fine.
+default: true
+MD013: false          # line length — tables and URLs make this noise
+MD033:                # inline HTML: allow the few tags GitHub renders
+  allowed_elements: [br, details, summary, img, sub, sup]
+MD041: false          # first line need not be an H1 (badges, templates)
+MD024:
+  siblings_only: true # duplicate headings allowed in different sections

CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Conventions
+
+Two kinds of writer share this repository: the daily-dev-agentic connector,
+which appends lessons on a schedule, and Claude sessions or humans, who add
+verified fact sheets and fix things. These rules keep them from colliding.
+
+## What the connector owns
+
+- `knowledge.md` and `lessons/*.md` are connector-managed. Edit them only to
+  fix a factual or formatting error in an existing lesson; do not add lessons
+  by hand (they would not carry a seen-post watermark and could be duplicated
+  on the next run).
+- The connector commits straight to `main`. Do not move these files, rename
+  the H1, or change the `## YYYY-MM-DD` section format; the connector and
+  `harness/check-knowledge.py` both depend on it.
+
+## What sessions and humans own
+
+- `verified/YYYY-MM-DD_topic_vN.md`: a fact sheet proven in a session with
+  tool output, not read in an article. Start with an H1, say where the
+  evidence came from, mark anything unverified as such. A revision is a new
+  `vN`, never an overwrite.
+- `README.md`, `CONTRIBUTING.md`, `LEDGER.md`, `harness/`, `.github/`.
+
+## Branches and pull requests
+
+- Hand or session changes go on `claude/<topic>` and land through a pull
+  request. Connector commits are the one exception.
+- The PR body says what changed, pastes the `check-knowledge.py` result, and
+  names the risk.
+- Merge only on green CI.
+
+## Ledger
+
+Every hand or session change adds one row to `LEDGER.md` (newest first).
+Connector runs are not logged there; their trail is the git history of
+`knowledge.md`.
+
+## Lint
+
+`.markdownlint.yml` is lenient on purpose (no line-length rule, inline HTML
+allowed) so connector output passes unchanged. Run
+`npx markdownlint-cli2@0.23.3 "**/*.md"` (the version CI pins) before opening a PR.

LEDGER.md

@@ -0,0 +1,15 @@
+# Ledger
+
+One row per hand-made or session-made change. Newest first. Connector runs are
+not logged here; `git log -- knowledge.md` is their trail.
+
+Columns: **Date** is UTC. **Session** is the claude.ai/code link or `hand`.
+**Outcome** is one of `merged`, `closed`, `open`, `direct` (committed to main).
+**Evidence** is the commit, PR, or harness result that proves it.
+
+| Date | Session | Branch | PR | Outcome | Evidence |
+| --- | --- | --- | --- | --- | --- |
+| 2026-09-27 | [session_01T7N2VsxDrRZPwWM7zdFnuK](https://claude.ai/code/session_01T7N2VsxDrRZPwWM7zdFnuK) | `claude/face-lift-v1` | #1 | open | correction: `verified/2026-09-26_claude-surfaces_v2.md` (session ran in the chat/Cowork tab, not the Code tab — T's correction 2026-09-27); v1 banner-marked superseded |
+| 2026-09-27 | [session_01T7N2VsxDrRZPwWM7zdFnuK](https://claude.ai/code/session_01T7N2VsxDrRZPwWM7zdFnuK) | `claude/face-lift-v1` | #1 | open | README restructure, CONTRIBUTING, ledger, `harness/check-knowledge.py` (RESULT: PASS — 12 pass, 0 warn, 0 fail after review fixes), lint CI, description + topics set via `gh` on the linked PC; follow-up pushes fix 3 Sourcery + 129 Codex findings, 1 pushed back with evidence (27 rounds; rounds 22-25 also rewrote 14 earlier suite cases whose vehicle or CommonMark reading no longer held, each checked against commonmark.js 0.31.2 or by mutation) |
+| 2026-09-26 | [session_01T7N2VsxDrRZPwWM7zdFnuK](https://claude.ai/code/session_01T7N2VsxDrRZPwWM7zdFnuK) | `main` | — | direct | commit `ef0c3ac`: `verified/2026-09-26_claude-surfaces_v1.md` |
+| 2026-08-24 | Cowork session | `main` | — | direct | commits `27aa529`…`0763bf4`: repo bootstrap, first 5 lessons (`cfd032a`), README |

README.md

@@ -1,9 +1,69 @@
 # agent-knowledge
 
-The readable memory of T's daily-dev-agentic loop. Written by the daily.dev MCP connector (Cloudflare Worker `dailydevplugd`).
+[![Lint](https://github.com/lookathim010-source/agent-knowledge/actions/workflows/lint.yml/badge.svg)](https://github.com/lookathim010-source/agent-knowledge/actions/workflows/lint.yml)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+![Written by: daily-dev-agentic connector](https://img.shields.io/badge/written%20by-daily--dev--agentic%20connector-blue)
+![Lessons carry a confidence score](https://img.shields.io/badge/lessons-confidence--scored-orange)
 
-- `knowledge.md` — all lessons, newest day first; every lesson links its daily.dev source post.
-- `lessons/YYYY-MM-DD.md` — the same lessons as one file per day.
-- `verified/YYYY-MM-DD_topic_vN.md` — session-verified fact sheets written by Claude sessions (not daily.dev lessons); hand-maintained.
+The readable memory of T's **daily-dev-agentic** loop: what the agent learned
+from daily.dev, distilled into lessons that name why each one matters for the
+stack (Claude Code, MCP, multi-agent systems, LangGraph, Firebase, Python,
+Rust, local LLMs, fintech infrastructure) and what to do about it.
 
-Each lesson is distilled by the agent from community-vetted daily.dev posts on T's stack (Claude Code, MCP, multi-agent systems, LangGraph, Firebase, Python, Rust, local LLMs, fintech infra) and carries a confidence score. Run state (seen-post watermark, counters) lives in Cloudflare KV, not here. Hand edits are safe — the connector only ever inserts and de-duplicates by source link.
+Written mostly by a machine. The daily.dev MCP connector (Cloudflare Worker
+`dailydevplugd`) appends lessons after each scheduled run; Claude sessions
+add verified fact sheets; humans fix typos. Run state (seen-post watermark,
+counters) lives in Cloudflare KV, not here.
+
+## Layout
+
+| Path | What it holds | Written by |
+| --- | --- | --- |
+| `knowledge.md` | Every lesson, newest day first. Each links its daily.dev source post and carries a confidence score | Connector (`knowledge_append`) |
+| `lessons/YYYY-MM-DD.md` | The same lessons, one file per day | Connector |
+| `verified/YYYY-MM-DD_topic_vN.md` | Fact sheets verified live in a Claude session, not daily.dev lessons. Revisions bump `vN` | Claude sessions, hand-maintained |
+| `harness/check-knowledge.py` | PASS/FAIL check that the files above still have the shape readers rely on | Run by CI and by sessions |
+| `LEDGER.md` | One row per hand-made or session-made change (connector runs are not logged here) | Sessions and hand edits |
+
+## How a lesson is shaped
+
+```markdown
+## 2026-08-24
+
+- **One actionable sentence, supported by the article.**
+  - Why it matters here: the link to T's stack or a live project.
+  - Do: the concrete next action, or "None now".
+  - Source: [Title](https://...) — Author (⬆️ upvotes · 💬 comments) · tags: a, b · confidence 80%
+```
+
+Confidence follows the connector's scale: official docs or maintainer posts
+around 80–95, well-upvoted practitioner posts 60–80, single opinions 30–55.
+Zero lessons on a quiet day is a valid result; the loop is told never to pad.
+
+## Reading it
+
+- Newest first: open `knowledge.md` and read from the top.
+- One day: open `lessons/<date>.md`.
+- Something proven rather than read: `verified/`.
+- Programmatically: the connector's `knowledge_read` tool (`days: N`) returns
+  the same content without cloning.
+
+## Checking it
+
+```bash
+python3 harness/check-knowledge.py          # PASS/FAIL lines
+python3 harness/check-knowledge.py --json   # same, as one JSON object
+```
+
+CI runs this plus markdownlint on every pull request and on every push to
+`main` (`.github/workflows/lint.yml`). Run it locally before pushing a branch.
+
+## Hand edits
+
+Safe. The connector only inserts and de-duplicates by source link; it never
+rewrites what is already there. Conventions for edits, fact sheets and the
+ledger are in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).