janezicmatej/.dotfiles
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

merge: claude config update

Browse Source
This commit is contained in:
Matej Janezic
2026-10-16 18:40:24 +02:00
parent 110105f902 bff697bf63
commit 3e7c76aed7
17 changed files with 2217 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
.gitignore vendored
View File

@@ -100,6 +100,7 @@ sway/scripts/*
!bin
bin/*
!bin/ssh-menu
!bin/git-sign-branch
# swaync
!swaync
@@ -124,3 +125,12 @@ claude/*
!claude/settings.json
!claude/statusline-command.sh
!claude/rules
!claude/agents
!claude/skills
claude/skills/*
!claude/skills/matej
!claude/skills/notes
claude/skills/notes/*
!claude/skills/notes/SKILL.md
!claude/skills/notes/notes.css
!claude/skills/notes/notes.py

74
bin/git-sign-branch Executable file
View File

@@ -0,0 +1,74 @@
#!/usr/bin/env bash
# git sign-branch [-n] [--reset-author] [<branch> [<upstream>]]
# re-creates every commit in <upstream>..<branch> with a signature, keeping trees, parents (mapped to
# the new ids), author, committer, dates and message byte for byte; merges are copied, never re-run
# --reset-author: author and committer become this repo's user.name and user.email (the signer); dates stay
# a branch with a merge of a signed tag (mergetag header) is refused, commit-tree can't carry the tag over
set -euo pipefail
dry=0 reset=0
while [[ ${1:-} == -* ]]; do
case $1 in
-n | --dry-run) dry=1 ;;
--reset-author) reset=1 ;;
*) echo "unknown option: $1" >&2; exit 1 ;;
esac
shift
done
if (( reset )); then
me_name=$(git config user.name) me_email=$(git config user.email)
fi
branch=${1:-$(git symbolic-ref --short HEAD)}
upstream=${2:-main}
ref=refs/heads/$branch
old_tip=$(git rev-parse --verify "$ref^{commit}")
git rev-parse --verify -q "$upstream^{commit}" >/dev/null || { echo "no such upstream: $upstream" >&2; exit 1; }
# checked before anything is signed, so a refusal leaves no partial work
tagged=()
while read -r c; do
if [[ -n $(git cat-file commit "$c" | sed -n '1,/^$/{/^mergetag /p}') ]]; then
tagged+=("$(git log -1 --format='%h %s' "$c")")
fi
done < <(git rev-list "$upstream..$old_tip")
if (( ${#tagged[@]} )); then
echo "refusing to sign $branch: commit-tree can't carry over the signed tag these merges embed (mergetag):" >&2
printf ' %s\n' "${tagged[@]}" >&2
exit 1
fi
declare -A new # old id -> new id, only for commits in the range
msg=$(mktemp); trap 'rm -f "$msg"' EXIT
count=0
while read -r c parents; do
args=() changed=0
for p in $parents; do
np=${new[$p]:-$p}; [[ $np != "$p" ]] && changed=1
args+=(-p "$np")
done
# a commit already signed, with the same parents (and, with --reset-author, already ours) stays as it is
mine=1
if (( reset )) && [[ $(git log -1 --format='%an%x1f%ae%x1f%cn%x1f%ce' "$c") != "$me_name"$'\x1f'"$me_email"$'\x1f'"$me_name"$'\x1f'"$me_email" ]]; then mine=0; fi
if (( !changed && mine )) && git verify-commit "$c" >/dev/null 2>&1; then new[$c]=$c; continue; fi
count=$((count + 1))
if (( dry )); then
echo "would sign $(git log -1 --format='%h %s' "$c")"; new[$c]=dry-$c; continue
fi
git cat-file commit "$c" | sed '1,/^$/d' >"$msg" # message bytes after the header block
# a non-utf-8 commit keeps its encoding header; names are read in it so their bytes stay too
enc=$(git cat-file commit "$c" | sed -n '1,/^$/{s/^encoding //p}')
enc=${enc:-UTF-8}
IFS=$'\x1f' read -r an ae ad cn ce cd < <(git log -1 --encoding="$enc" --date=raw --format='%an%x1f%ae%x1f%ad%x1f%cn%x1f%ce%x1f%cd' "$c")
if (( reset )); then an=$me_name ae=$me_email cn=$me_name ce=$me_email; fi
new[$c]=$(GIT_AUTHOR_NAME=$an GIT_AUTHOR_EMAIL=$ae GIT_AUTHOR_DATE=$ad \
GIT_COMMITTER_NAME=$cn GIT_COMMITTER_EMAIL=$ce GIT_COMMITTER_DATE=$cd \
git -c i18n.commitEncoding="$enc" commit-tree -S "${args[@]}" -F "$msg" "$c^{tree}")
done < <(git rev-list --reverse --topo-order --parents "$upstream..$old_tip")
if (( dry )); then echo "$count commit(s) to sign on $branch"; exit 0; fi
new_tip=${new[$old_tip]:-$old_tip}
[[ $(git rev-parse "$new_tip^{tree}") == $(git rev-parse "$old_tip^{tree}") ]] || { echo "tip tree differs, ref left alone" >&2; exit 1; }
# compare-and-swap: fails if the branch moved while we were signing
git update-ref -m "sign-branch: signed $count commit(s)" "$ref" "$new_tip" "$old_tip"
echo "$branch: $old_tip -> $new_tip ($count signed); undo: git update-ref $ref $old_tip"

28
claude/CLAUDE.md
View File

@@ -4,28 +4,24 @@
- for plans, reports, design docs, and anything benefiting from diagrams, styling, or embedded images, prefer HTML over Markdown
- for conventional files (README, CONTRIBUTING, LICENSE, CHANGELOG, etc.) use the ecosystem default
## Notes
- local design docs, work handoffs and parked questions live in `.notes/` per project (see ~/.config/claude/rules/notes.md)
## Diagnostics
- IMPORTANT: pursue root cause before proposing a fix; never propose a manual workaround before identifying the underlying cause
- if a fix doesn't resolve the symptom, dig deeper instead of layering patches
- verify the fix addresses the reported behavior, not just that the error went away
- for system/boot/network/regression bugs, write a root-cause hypothesis first (see ~/.config/claude/rules/diagnostics.md)
- IMPORTANT: find the root cause before proposing a fix; never present a workaround as a fix (see ~/.config/claude/rules/diagnostics.md)
- if a fix doesn't resolve the symptom, revisit the cause instead of layering patches
## Trust & verification
- IMPORTANT: don't present plausible-sounding details as facts; verify file paths, flags, function and library behavior by reading code or docs first
- when a claim depends on external behavior (library APIs, system semantics, game mechanics, etc.), cite the source you verified against, or mark it as unverified
## Planning vs execution
- IMPORTANT: when asked to "plan", "analyze", "deep-dive", or "research", produce documents only; no Edit/Write (except to the plan file) or Bash mutations until approved
- IMPORTANT: when asked to "plan", "analyze", "deep-dive", or "research", produce documents only; no Edit/Write (except to the plan file or `.notes/`) or Bash mutations until approved
- if a request is ambiguous between planning and implementing, ask which one
## Scope
- if a diff grows beyond the original request, stop and confirm before continuing
## Workflow
- when redirected or interrupted, stop the current approach immediately and follow the new direction without explaining or defending it
- focus on one goal per session; don't drift into unrelated improvements
- implement changes directly; don't use sub-agents/Task for simple operations like renames, file moves, or single-file edits
- use Task agents only for genuinely complex parallel exploration or research, not for straightforward implementation
- don't start unrelated work on your own; if a diff grows beyond the request, stop and confirm
- in orchestrated work (the `matej` skill), an agent working from a brief stays inside the brief instead: it notes anything outside it as a leftover and keeps going
## Comments
- lowercase, no trailing punctuation
@@ -35,5 +31,9 @@
- keyword comments must always include the `(@janezicmatej)` attribution
## Git
- agents MUST commit with `--no-gpg-sign`
- when implementing multi-step work, split into logical commits the user can review and stage independently; don't bundle everything into one
- agents never sign commits, in any form: they are not me. commit with `--no-gpg-sign`; I re-sign branches on my host (`git sign-branch`) before they are pushed
- use the identity git already has; where it has none, commit as `-c user.name=agent -c user.email=agent@sandbox.invalid` (my host signing resets the author)
- commit messages: a conventional-commit subject line of at most 72 characters including the prefix; a body only where the project wants one, wrapped at 72; no trailers
- stage paths explicitly; never `git add .` or `git add -A`
- split multi-step work into a few logical commits I can review; condense fixups before handing a branch back
- every branch, worktree and container you create is yours to remove when the work ends; never remove ones you did not create

10
claude/agents/explorer.md Normal file
View File

@@ -0,0 +1,10 @@
---
name: explorer
description: Builds one option for an open design question in Matej's projects, as something he can inspect (runnable code on a prototype branch, a canvas frame), often alongside another explorer working the same brief independently. Use when the lead wants options to compare before deciding.
---
You answer an open question with an option Matej can look at and judge, not with a final implementation. Prototypes may cut corners where it doesn't change what he is judging; say which corners. If another explorer works the same brief, don't look at its work.
Read `~/.config/claude/CLAUDE.md` and the project's AGENTS.md first. Work on the prototype branch your brief names; never merge, never push, never sign. Make the option inspectable the way the brief asks (a preview he can run on his host, screenshots, a frame), and leave what he needs to look at in place; stop your own servers and containers.
Your reply is text: what the option is and why, how to look at it (exact commands and URLs), what you tried and dropped, its weak spots, what you created.

10
claude/agents/junior.md Normal file
View File

@@ -0,0 +1,10 @@
---
name: junior
description: Implementer for one part of a larger unit of work, briefed by a senior agent - builds its part on its own branch and worktree, runs the checks for it, and reports back for review. Use when a senior splits work into parallel parts.
---
You build one part of a unit of work that a senior agent owns. Stay inside your brief: anything outside it goes in your report as a leftover, not into your branch. When the brief leaves a choice, take the simplest option and say so.
Read `~/.config/claude/CLAUDE.md`, the project's AGENTS.md and the house-rule skills it points to before writing code. Work on the branch and worktree your brief names; commit a few logical commits, never sign, never merge, never push.
Run the checks your brief lists before reporting, and stop your own servers and containers when you are done. Your reply is text: the branch and commits, what you built, the checks with their results, anything you could not do or verify, what you created.

8
claude/agents/researcher.md Normal file
View File

@@ -0,0 +1,8 @@
---
name: researcher
description: Answers a factual or technical question for Matej with sources and, where it can, a test in a throwaway sandbox - e.g. how a git or library feature behaves, which of several approaches holds up. Use when the lead needs a verified answer, not an implementation.
---
You find out, and you show how you know. Check claims against primary sources (official docs, man pages, source code) and cite them; mark anything you could not verify. Where a claim can be tested, test it in a throwaway setup under `$SANDBOX_VM_STATE/<your topic>/` and show the trimmed commands and output; never touch real keyrings, credentials or project repos.
Read `~/.config/claude/CLAUDE.md` first for how Matej wants facts handled. Your reply is text: the answer first (a short recommendation), then the evidence per option, then what is unverified. Leave your sandbox folder for review and say where it is.

12
claude/agents/senior.md Normal file
View File

@@ -0,0 +1,12 @@
---
name: senior
description: Senior developer for one unit of work in Matej's projects - builds it on a branch (alone or with junior agents in parallel), reviews and condenses their work, runs every check, and hands back one branch that already works. Use when the lead session delegates implementation from a brief.
---
You are the senior developer for one unit of work. The lead session that briefed you talks to Matej; you don't, so when the brief leaves a choice, take the simplest option that works, keep going, and list it under "decided along the way".
How Matej likes this run is in `~/.config/claude/skills/matej/SKILL.md` (roles, ownership, clean-up) and `~/.config/claude/CLAUDE.md` (git, comments, verification). Read both, then the project's AGENTS.md and any house-rule skills it points to, before writing code.
You own the result: a branch that works, lint and format clean, every test suite green the way CI runs it, the change looked at in a browser when it has UI, reviewed for bugs. Split work across `junior` agents in parallel when the parts don't step on each other; review each part before you take it in. Never merge into the main branch, never push, never sign. Remove every branch, worktree, container and server you or your juniors created once it is merged into your branch or no longer needed, and nothing you didn't create.
Your reply is text: the branch and its commits, what each delivers, the checks you ran with their results, what differs from the brief, what you decided along the way, what you created and removed, and what is left. Say plainly what you could not verify.

28
claude/rules/diagnostics.md
View File

@@ -1,26 +1,8 @@
# Diagnostics rules
Detailed root-cause discipline for system, boot, network, and regression bugs. The headline rules live in `CLAUDE.md`; this file is the long form.
The long form of the headline rules in `CLAUDE.md`.
## Root-cause hypothesis
Before proposing any fix for a system/boot/network/regression bug, write a "Root cause hypothesis" section with these four parts:
1. **Symptom** — the observable behavior, copied verbatim where possible (error message, missing output, wrong value)
2. **Proximate cause** — the immediate trigger, with evidence (file path + line, log excerpt, command output)
3. **Underlying cause** — why the proximate cause occurred; the layer of indirection that makes the proximate cause possible
4. **Ruled-out alternative** — at least one other plausible hypothesis you considered and why you discarded it
Only after writing all four parts should you propose a fix.
## Workaround discipline
- never present a manual workaround as a fix; if a workaround is the only option, label it explicitly as a workaround and describe what would need to change to make it unnecessary
- if a fix doesn't resolve the symptom on first try, don't layer another patch; revisit the hypothesis instead
- if you're tempted to add a try/except, retry loop, or feature flag to mask an error, stop and ask first
## Verification
- before declaring a fix done, re-run the failing check and confirm the reported behavior is now correct
- "the error message disappeared" is not sufficient; confirm the underlying behavior matches what was expected
- if the fix touches a process, daemon, or background job, confirm it cleaned up after itself (no orphaned procs, sockets, locks, temp files)
- Say what the cause is, with the evidence (file and line, log excerpt, command output), before proposing a fix. For system, boot, network and regression bugs, also say which other cause you ruled out and why.
- A workaround is labelled as one, with what would have to change to make it unnecessary. Don't mask an error with a try/except, a retry or a flag without asking first.
- If the fix doesn't resolve the symptom, go back to the cause; don't stack another patch on top.
- Done means the reported behaviour is now right, checked by re-running what failed. An error that went away is not enough. If the fix touched a process, daemon or background job, check it left nothing behind (processes, sockets, locks, temp files).

78
claude/rules/notes.md Normal file
View File

@@ -0,0 +1,78 @@
# Notes rules
Each project keeps its local working notes in `.notes/` at the project root: design docs, work that spans sessions, and questions parked for later. The notes are never committed to the project. The `notes` skill does the mechanics (creating the dir, picking ids, close-out).
## Layout
```
.notes/ # its own git repo, never pushed
README.md # one line pointing here
index.html # generated: the overview, links only
notes.css # generated: copy of the skill's stylesheet every page uses
_pages/ # generated: questions, briefs and other markdown rendered to pages
_out/ # generated: other/out/ made self-contained, css inlined, for sending
docs/ # dNNN-slug.html, or dNNN-slug/index.html with its assets
work/ # wNNN-slug/ while in flight, removed at close-out
questions/ # qNNN-slug.md, removed when settled
other/
in/ # placed by the user
out/ # prepared for someone else
```
- created on first need (the first doc, work item or question in a project), not up front
- the generated files are rebuilt by the skill's `notes.py` on every commit and never committed; browse every project's notes at once with `notes.py serve` (one port, roots `$NOTES_ROOTS`, else `~/git`), or one project with `python -m http.server -d .notes`
- every page has a back link to the index; ids like `d007` or `q014` in markdown become links
## Numbering
- `<letter><NNN>-<slug>`: `d` docs, `w` work, `q` questions; each letter has its own counter, three digits, lowercase kebab slug
- numbers are never reused, including numbers of deleted items: the next id is the highest ever used in that bucket (files plus `git -C .notes log --all --name-only`) + 1
- refer to items by id everywhere: chat, other notes, commit subjects ("see q014", "per d007")
- `other/` is not numbered
## docs
- point-in-time design docs: plans, proposals, research, reviews; html per the output format rules
- one look for all docs: link `notes.css`, start `main.page` with `nav.back`, use only the components documented at the top of `notes.css`, no `<style>` or font links of their own; the skill shows the skeleton
- a doc with assets becomes a folder: `dNNN-slug/index.html` plus its files, linked relatively
- a status line sits directly under the title as `<p class="status current|stale|superseded">…</p>` (`notes.py` reads it): `status: current`, `status: partly stale (<what changed>, <date>)` or `status: superseded by dNNN (<date>)`, with `dNNN` a relative link to the newer doc
- once done, a doc's body doesn't change; only its status line does. a new design gets a new doc
## work
- one folder per piece of work that spans sessions; a single-session task gets none
- typical files: `brief.md` (goal, done when, scope, decisions to ask), `plan.html` (the proposal to approve), `report.md` (what was built, what differs, leftovers), plus research the work needed
- close-out runs in the same session the work ends (branch merged or work dropped):
1. lasting design goes to `docs/`: a new doc, or a status line on an existing one
2. leftovers go to `questions/`, one each, with `origin: wNNN`
3. delete the folder and commit
- a folder untouched for weeks with no open branch gets flagged to the user, not closed silently
## questions
- one file per item: something deferred, handed off or out of scope for the current session
- frontmatter: `created` (date), `origin` (`wNNN`, `dNNN`, a branch, or `<commit>:<path>` in `.notes`), `status: open`
- body: what is open, why it matters, what is known, where to look
- before acting on one, check the repo for whether it still applies
- settled: fold the outcome into a doc or a work item if it is worth keeping, delete the file, commit with a subject saying how it was settled
## other
- `in/`: read only when the user points at it
- `out/`: written for a person, not for later sessions; don't treat it as context
- html in `out/` uses the same `notes.css` and components as docs, without an id or status line; the copy that leaves is the generated self-contained one in `_out/`
- `out/` holds documents and the few small files that go with them (a script, a config snippet); bulk output for a person (screenshot sets, builds, logs) does not go into `.notes/` at all: in a sandbox vm it goes to the host handoff mount once there is one, until then ask where
## History
- `.notes/` is its own git repo with no remote, its `.gitignore` holding the generated files; commit after each change set, subject line only, naming the ids touched (`q014: settled by a3f4573`)
- git history replaces archives: delete instead of moving to an archive folder, rewrite instead of keeping dated copies
- never stage `.notes/` from the project repo: stage project paths explicitly, never `git add .` or `git add -A` there
- the host's global gitignore hides `.notes/`; where it shows up as untracked (sandbox vms), that is expected
## What doesn't go in notes
- facts every session needs: the project's `AGENTS.md`/`CLAUDE.md`, or memory when they are personal
- anything teammates need: the project repo
- secrets
- committed project files never reference `.notes/` paths

57
claude/skills/matej/SKILL.md Normal file
View File

@@ -0,0 +1,57 @@
---
name: matej
description: How Matej likes larger work run - one lead session that talks to him and briefs agents, a senior agent that builds and hands back a checked branch, explorer agents for open questions, notes and a design canvas for review. Use when he asks for orchestrated work ("let the senior handle it", "spawn agents for this", parallel options to compare) or for work spanning several branches or sessions.
---
# Running work through agents
Guidelines, not a procedure. Where a step is obvious, do it your way; what is written here is what isn't knowable from the repo.
## Roles
- **Lead**: the session Matej talks to. Discusses, locks decisions, keeps the notes, briefs agents, checks what they report and tells him plainly what is done, what is open and what it took on trust. It doesn't edit the project itself, so its context stays free for judgement.
- **Senior**: owns a unit of work from brief to a branch that works, and hands back that one branch, never merging it.
- When the work splits into parts that don't step on each other, it runs implementer agents in parallel, each on its own branch and worktree under the work id, briefed the way the lead briefs it. A few at a time; what everything else builds on (a shared shell, a schema) goes first, alone. Small or tightly coupled work it does itself.
- It reviews each part before taking it in (reads the diff, runs code-review and simplify, fixes what is real), condenses its history, and merges it into the work's integration branch, sorting out what parallel parts collide on (migrations, generated code).
- It runs every check the project has on the integration branch, not only on the parts, and looks at what changed in a browser when there is UI.
- It removes its implementers' branches, worktrees and containers once they are merged, and its own when it hands back; the lead checks.
- **Explorers**: answer an open question with something Matej can inspect, often two independently on the same brief so he can compare. Prototypes may cut corners; they never land as they are.
## Protocol
- Discuss, lock, relay. Only locked decisions go to builders, in the words that were agreed. When a relay replaces an earlier one, say what it replaces; when unsure what Matej meant, ask before relaying.
- Builders keep going while the next point is discussed; new locked items join the open branch.
- Builders decide what the brief doesn't settle the simple way and list it as "decided along the way". Only the lead asks Matej.
## Spawning
Use the agent types for the roles (`senior`, `junior`, `explorer`, `researcher` in `~/.config/claude/agents/`), not a general-purpose agent, so Matej sees who is doing what. An agent's label is set once, when it is spawned, so make it the top level: the unit of work it is for ("graph redesign", "how it works redraw", "signing agent commits"), never its first step. What it is doing right now is the activity Claude Code shows beside the label; that part takes care of itself. When a running agent is given a new item, the label stays as it was, so say the new item in the relay's first line.
## A brief carries
The goal and what done looks like; where the spec is (note ids, canvas frames, branches); the decisions that touch it; scope and what not to touch; pointers to the rules (AGENTS.md, CLAUDE.md, the house skills) rather than copies; the checks; the shape of the reply; what it may create and must clean up. Agents don't see the lead's memory: anything they need from it goes in the brief.
## Before passing a report on
Check the cheap facts yourself: branch heads, commit authors and subject lengths, nothing staged that shouldn't be, worktrees and containers gone. Re-run something long only when a claim looks off. Say what you checked.
## Where things go
- Plans, decisions, reports, leftovers: the project's `.notes/` (the notes skill). Agents can't write there; the lead files their reports.
- Visual design to discuss: the Design canvas (an Artifact), kept current; history frames get removed, not piled up.
- Prototypes and finished work: branches. The repo's `.git` is on Matej's host, so he can `git worktree add --detach` any branch there.
- Bulk files for Matej (screenshots, logs): the host handoff mount once it exists; never the project repo, never bulk in `.notes/`.
## Ownership and clean-up
- Everything a unit of work creates carries its work id: branches `<wNNN>/<name>`, worktrees under `$SANDBOX_VM_STATE/wt/<wNNN>/`, containers `<wNNN>-<name>`. Agents remove what they created and nothing else.
- The lead keeps `made.md` in the work item: each branch, worktree, container and handoff folder, with its state (open, merged, prototype).
- Close-out removes the list: merged branches deleted, prototypes once their decision is recorded, worktrees, containers and handoff folders gone; then check nothing under the work id is left.
## Interruptions
Any agent can stop (usage limits, Matej stopping it), and a stopped agent can't be resumed. Keep state on disk: small commits on the branch, decisions and reports in the work item. Before re-briefing, look at the repo first and hand the new agent what is actually there.
## Git
Agents never sign; Matej re-signs on his host before pushing (CLAUDE.md, Git).

116
claude/skills/notes/SKILL.md Normal file
View File

@@ -0,0 +1,116 @@
---
name: notes
description: Manage the project's local .notes/ dir (design docs, work handoffs, parked questions). Use whenever writing a design doc, plan, proposal, research or review for local use; starting, handing off or closing out work that spans sessions (brief, plan, report); parking something for later, out of scope or a follow-up; picking up or settling a parked question; preparing a document for someone else; or when the user mentions .notes, handoffs, open questions or asks what is pending.
---
# Notes
The policy is `~/.config/claude/rules/notes.md`: layout, numbering, status lines, close-out, what doesn't belong. This skill holds the procedures. Every step that changes `.notes/` ends with `commit`, which also regenerates `index.html`, `notes.css`, the markdown pages under `_pages/` and the portable copies under `_out/`. Change the look only in this skill's `notes.css`, never in a project.
```
N=~/.config/claude/skills/notes/notes.py
python3 $N init # create .notes/ if missing (idempotent)
python3 $N next d|w|q # next free id, counts deleted items too
python3 $N commit "<subject>" # regenerate the generated pages, commit all of .notes/
python3 $N index # regenerate index.html, notes.css, _pages/ and _out/ only
python3 $N serve # every project's notes on http://127.0.0.1:8765/: hub filters projects, each project page searches its notes (the user runs this)
```
All commands take `--root <project>`; the default is the git toplevel of the current dir. Never pick an id by hand or from `ls`; deleted ids live only in git history.
## New doc
1. `init`, then `next d`
2. write `docs/dNNN-slug.html` (or `docs/dNNN-slug/index.html` with its assets next to it, then every `../` below becomes `../../`) on this skeleton, using only the components documented at the top of `notes.css` (callout, tag, cards, grid-2, table, figure.diagram with its svg classes); no `<style>`, no font links:
```html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Short name</title>
<link rel="stylesheet" href="../notes.css">
</head>
<body>
<main class="page">
<nav class="back"><a href="../index.html">← notes</a></nav>
<header>
<p class="eyebrow">dNNN · plan · 2026-10-14</p>
<h1>Title</h1>
<p class="status current">status: current</p>
<p class="lede">What this doc decides, in one or two sentences.</p>
</header>
<section>
<h2>…</h2>
</section>
</main>
</body>
</html>
```
3. if it replaces an older doc, set the older one's status line to `<p class="status superseded">status: superseded by <a href="dNNN-slug.html">dNNN</a> (<date>)</p>`; mind the relative path when either doc is a folder
4. look at it: a headless browser screenshot in light and dark, or `serve`
5. `commit "dNNN: <slug>"`
## New work item
Only for work that will span sessions.
1. `init`, then `next w`, create `work/wNNN-slug/`
2. `brief.md`, starting with `# wNNN <title>`: goal, done when, scope, verification, decisions to ask, prerequisites to read
3. add `plan.html` (the proposal, on the doc skeleton with `../../notes.css` and `../../index.html`) and research files as the work goes; `report.md` at the end: what was built, what differs from the plan, leftovers
4. `commit "wNNN: <what changed>"`
## Close-out
When the work's branch is merged or the work is dropped, in that same session:
1. lasting design → new doc or a status line on an existing one (see above)
2. each leftover → a question with `origin: wNNN`
3. `rm -r work/wNNN-slug`, then `commit "wNNN: closed, <merged as <sha>|dropped>"`
When `index` shows a work folder untouched for weeks with no open branch in the project, tell the user; don't close it yourself.
## Park a question
1. `init`, then `next q`
2. write `questions/qNNN-slug.md`:
```
---
created: 2026-10-14
origin: w009
status: open
---
# <one-line question or follow-up>
What is open and why it matters. What is known so far, with paths, commits and ids.
Where to start looking.
```
3. `commit "qNNN: <slug>"`
Write it so a session with no memory of today can act on it.
## Settle a question
1. check the repo first: it may already be done or moot
2. fold the outcome into a doc or a work item if it is worth keeping
3. `rm questions/qNNN-slug.md`, `commit "qNNN: settled, <how: done in <sha> | moot because ... | moved to wNNN>"`
## Other
- `other/in/`: the user's files; read only when pointed at
- `other/out/`: documents for someone else, written for that reader; no ids, no status line
- html follows the doc skeleton and components like any doc, with `../../notes.css` and `../../index.html`; the eyebrow names the reader and date instead of an id (`for the team · 2026-10-14`)
- what gets sent is the generated `_out/<file>`: `notes.css` inlined, back link dropped, other files copied; the index links it as "to send"
- look at the `_out/` copy too before handing it over, then `commit "other: <file>"`
## Never
- stage `.notes/` from the project repo (`git add .`, `git add -A`); stage project paths explicitly
- reference `.notes/` paths from committed project files
- keep archives or dated copies; delete, git keeps it
- push `.notes/` or add a remote

961
claude/skills/notes/notes.css Normal file
View File

@@ -0,0 +1,961 @@
/*
* notes.css: the one stylesheet for every page in a project's .notes/
* notes.py copies it to .notes/notes.css; edit it here, in the notes skill, never in a project
*
* gruvbox material (sainnhe/gruvbox-material: medium contrast, material foreground), light or dark
* by the system scheme; jetbrains mono for all text
*
* page skeleton for a doc (docs/dNNN-slug.html; one level deeper for a folder doc):
* <link rel="stylesheet" href="../notes.css">
* <body><main class="page">
* <nav class="back"><a href="../index.html">← notes</a></nav>
* <header>
* <p class="eyebrow">d007 · 2026-10-13</p>
* <h1>Title</h1>
* <p class="status current|stale|superseded">status: …</p>
* <p class="lede">one or two sentences</p>
* </header>
* <section><h2>…</h2> …</section>
* </main></body>
*
* components:
* .callout (+ .good .warn .bad .info) a boxed note, recommendation, open point
* .tag (+ .good .warn .bad .info .muted) a small inline label
* .cards > .card (.card-id, strong, small) a grid of linked or plain cards
* .grid-2 two columns, one on a phone
* .table > table a table that scrolls sideways when wide
* figure.diagram > svg (+ figcaption) an inline svg diagram, see "diagrams" below
* dl.facts > dt + dd label and value pairs in two columns (repro, cause, fix)
* pre.diff > span(.add .del) a unified diff, one span per line
* .legend > span > svg + text a row of notation keys above a diagram
* .swatch (+ .info .good .warn .bad) a small colour square that matches a diagram box
* main.page.wide a wider page, for pages carried by wide diagrams
* .sub, .muted secondary text
* .fix a line prefixed with an arrow
*/
@import url("https://fonts.googleapis.com/css2?family=JetBrains+Mono:ital,wght@0,400;0,500;0,600;0,700;1,400&display=swap");
:root {
color-scheme: light dark;
--radius: 0.375rem;
/* gruvbox material light */
--red: #c14a4a;
--orange: #c35e0a;
--yellow: #b47109;
--green: #6c782e;
--aqua: #4c7a5d;
--blue: #45707a;
--purple: #945e80;
--background: #fbf1c7;
--foreground: #654735;
--card: #f4e8be;
--muted: #eee0b7;
--muted-foreground: #7c6f64;
--border: #ddccab;
--input: #a89984;
--link: var(--blue);
/* text colours and their tints, both follow the scheme's palette */
--good: var(--green);
--warn: var(--yellow);
--bad: var(--red);
--info: var(--blue);
--good-bg: color-mix(in srgb, var(--green) 14%, transparent);
--warn-bg: color-mix(in srgb, var(--yellow) 16%, transparent);
--bad-bg: color-mix(in srgb, var(--red) 13%, transparent);
--info-bg: color-mix(in srgb, var(--blue) 13%, transparent);
--accent: var(--orange);
--accent-bg: color-mix(in srgb, var(--orange) 12%, transparent);
--font-mono: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, monospace;
}
@media (prefers-color-scheme: dark) {
:root {
/* gruvbox material dark */
--red: #ea6962;
--orange: #e78a4e;
--yellow: #d8a657;
--green: #a9b665;
--aqua: #89b482;
--blue: #7daea3;
--purple: #d3869b;
--background: #282828;
--foreground: #d4be98;
--card: #32302f;
--muted: #45403d;
--muted-foreground: #a89984;
--border: #45403d;
--input: #5a524c;
--good-bg: color-mix(in srgb, var(--green) 16%, transparent);
--warn-bg: color-mix(in srgb, var(--yellow) 15%, transparent);
--bad-bg: color-mix(in srgb, var(--red) 16%, transparent);
--info-bg: color-mix(in srgb, var(--blue) 16%, transparent);
--accent-bg: color-mix(in srgb, var(--orange) 15%, transparent);
}
}
/* base */
*,
*::before,
*::after {
box-sizing: border-box;
}
html {
scrollbar-gutter: stable;
-webkit-text-size-adjust: 100%;
}
body {
margin: 0;
background: var(--background);
color: var(--foreground);
font: 400 14px/1.65 var(--font-mono);
-webkit-font-smoothing: antialiased;
}
main.page {
max-width: 860px;
margin: 0 auto;
padding: 24px 16px 96px;
}
main.page.wide {
max-width: 1240px;
}
a {
color: var(--link);
text-decoration: none;
}
a:hover {
text-decoration: underline;
}
a:focus-visible {
outline: 2px solid var(--blue);
outline-offset: 2px;
border-radius: 3px;
}
h1,
h2,
h3,
h4 {
font-weight: 600;
line-height: 1.25;
text-wrap: balance;
margin: 0;
}
h1 {
font-size: 26px;
}
h2 {
font-size: 19px;
margin: 44px 0 12px;
padding-top: 24px;
border-top: 1px solid var(--border);
}
h3 {
font-size: 16px;
margin: 28px 0 8px;
}
h4 {
font-size: 15px;
margin: 20px 0 6px;
}
section > h2:first-child {
margin-top: 40px;
}
p,
ul,
ol,
blockquote,
pre,
figure,
.table,
.callout,
.cards,
.grid-2,
details {
margin: 0 0 14px;
}
ul,
ol {
padding-left: 22px;
}
li + li {
margin-top: 4px;
}
li > ul,
li > ol {
margin: 4px 0 0;
}
strong,
b {
font-weight: 600;
}
hr {
border: 0;
border-top: 1px solid var(--border);
margin: 32px 0;
}
blockquote {
padding: 2px 0 2px 16px;
border-left: 3px solid var(--border);
color: var(--muted-foreground);
}
img {
max-width: 100%;
height: auto;
border-radius: var(--radius);
border: 1px solid var(--border);
}
code,
kbd,
pre,
.mono {
font-family: var(--font-mono);
font-size: 0.93em;
}
code {
background: var(--muted);
padding: 1px 5px;
border-radius: 4px;
overflow-wrap: break-word;
}
pre {
background: var(--card);
border: 1px solid var(--border);
border-radius: var(--radius);
padding: 12px 14px;
overflow-x: auto;
line-height: 1.5;
}
pre code {
background: none;
padding: 0;
font-size: 1em;
overflow-wrap: normal;
}
/* page chrome */
nav.back {
font-size: 13px;
margin-bottom: 28px;
}
nav.back a {
color: var(--muted-foreground);
}
nav.back a:hover {
color: var(--link);
}
header {
margin-bottom: 8px;
}
header > * + * {
margin-top: 10px;
}
.eyebrow {
font: 500 12px/1.4 var(--font-mono);
letter-spacing: 0.04em;
color: var(--muted-foreground);
margin: 0;
}
.lede {
font-size: 17px;
line-height: 1.6;
margin-top: 14px;
}
.sub,
.muted {
color: var(--muted-foreground);
}
p.status {
display: inline-block;
font-size: 13px;
line-height: 1.5;
padding: 3px 10px;
border-radius: 6px;
background: var(--muted);
color: var(--muted-foreground);
}
p.status.current {
background: var(--good-bg);
color: var(--good);
}
p.status.stale {
background: var(--warn-bg);
color: var(--warn);
}
.fix::before {
content: "→ ";
color: var(--accent);
font-weight: 600;
}
/* components */
.callout {
background: var(--card);
border: 1px solid var(--border);
border-left: 3px solid var(--input);
border-radius: var(--radius);
padding: 10px 14px;
}
.callout > :last-child {
margin-bottom: 0;
}
.callout.good {
background: var(--good-bg);
border-color: transparent;
border-left-color: var(--good);
}
.callout.warn {
background: var(--warn-bg);
border-color: transparent;
border-left-color: var(--warn);
}
.callout.bad {
background: var(--bad-bg);
border-color: transparent;
border-left-color: var(--bad);
}
.callout.info {
background: var(--info-bg);
border-color: transparent;
border-left-color: var(--info);
}
.tag {
display: inline-block;
font: 500 11px/1.5 var(--font-mono);
letter-spacing: 0.02em;
padding: 1px 8px;
border-radius: 99px;
white-space: nowrap;
vertical-align: 1px;
background: var(--muted);
color: var(--muted-foreground);
}
.tag.good {
background: var(--good-bg);
color: var(--good);
}
.tag.warn {
background: var(--warn-bg);
color: var(--warn);
}
.tag.bad {
background: var(--bad-bg);
color: var(--bad);
}
.tag.info {
background: var(--info-bg);
color: var(--info);
}
.cards {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
gap: 10px;
}
.card {
display: block;
background: var(--card);
border: 1px solid var(--border);
border-radius: var(--radius);
padding: 12px 14px;
color: var(--foreground);
}
a.card:hover {
border-color: var(--accent);
text-decoration: none;
}
.card-id {
display: block;
font: 500 12px/1.4 var(--font-mono);
color: var(--accent);
}
.card strong {
display: block;
}
.card small {
display: block;
color: var(--muted-foreground);
font-size: 13px;
}
.card > :last-child {
margin-bottom: 0;
}
.grid-2 {
display: grid;
grid-template-columns: 1fr 1fr;
gap: 12px;
}
@media (max-width: 720px) {
.grid-2 {
grid-template-columns: 1fr;
}
}
.table {
overflow-x: auto;
}
table {
border-collapse: collapse;
width: 100%;
font-size: 14px;
}
th,
td {
text-align: left;
vertical-align: top;
padding: 7px 10px;
border-bottom: 1px solid var(--border);
}
th {
font-weight: 600;
font-size: 13px;
color: var(--muted-foreground);
}
td > :last-child {
margin-bottom: 0;
}
td .tag {
white-space: normal;
}
td code {
overflow-wrap: anywhere;
}
details {
background: var(--card);
border: 1px solid var(--border);
border-radius: var(--radius);
padding: 8px 14px;
}
summary {
cursor: pointer;
font-weight: 500;
}
details[open] > summary {
margin-bottom: 8px;
}
dl.facts {
display: grid;
grid-template-columns: max-content minmax(0, 1fr);
gap: 6px 16px;
margin: 0 0 14px;
}
dl.facts dt {
color: var(--muted-foreground);
font-weight: 500;
}
dl.facts dd {
margin: 0;
}
@media (max-width: 560px) {
dl.facts {
grid-template-columns: minmax(0, 1fr);
gap: 0;
}
dl.facts dd + dt {
margin-top: 8px;
}
}
/* one column as wide as the longest line, so every line's tint spans it when scrolled */
pre.diff {
display: grid;
grid-template-columns: minmax(max-content, 1fr);
}
pre.diff span {
white-space: pre;
}
pre.diff .add {
background: var(--good-bg);
color: var(--good);
}
pre.diff .del {
background: var(--bad-bg);
color: var(--bad);
}
.legend {
display: flex;
flex-wrap: wrap;
gap: 8px 22px;
margin: 0 0 14px;
font-size: 13px;
color: var(--muted-foreground);
}
.legend > span {
display: inline-flex;
align-items: center;
gap: 8px;
}
.legend svg {
width: 34px;
height: 20px;
flex: none;
}
.swatch {
display: inline-block;
width: 10px;
height: 10px;
border-radius: 3px;
border: 1px solid var(--muted-foreground);
background: var(--card);
vertical-align: 0;
}
.swatch.info {
background: color-mix(in srgb, var(--blue) 14%, var(--card));
border-color: var(--blue);
}
.swatch.good {
background: color-mix(in srgb, var(--green) 14%, var(--card));
border-color: var(--green);
}
.swatch.warn {
background: color-mix(in srgb, var(--yellow) 18%, var(--card));
border-color: var(--yellow);
}
.swatch.bad {
background: color-mix(in srgb, var(--red) 14%, var(--card));
border-color: var(--red);
}
/*
* diagrams: inline svg inside figure.diagram, drawn with these classes so both schemes work
* <g class="node [accent|dashed|good|bad|warn]"><rect …/><text …>Label</text><text class="sub" …>detail</text></g>
* <path class="edge [back|good|bad|warn]" … marker-end="url(#arrow)"/>
* <path class="arrow [back|good|bad|warn]" d="M0 0 L10 5 L0 10 z"/> inside a <marker>
* <text class="edge-label [back|good|bad|warn]" …>label</text>
* <rect class="group" …/> and <text class="group-label" …> a dashed box around nodes
* for drawings with their own text placement (a data flow, a sequence), classes go on the shapes:
* <rect class="box [info|good|warn|bad|accent] [strong] [dashed] [open]"/> a step, process or entity
* <rect class="zone [info|good|warn|bad|accent] [boundary]"/> a tinted dashed area; boundary strokes it red
* <rect class="panel"/> a quiet solid area behind a group of boxes
* <rect class="chip [good|accent]"/> + <text class="chip-text"> a small filled badge or numbered dot
* <path class="line"/> a plain stroke (a data store's rails) <line class="rule"/> a faint dashed guide
* <rect class="fill"/> a borderless card-coloured shape: a data store's body, a backdrop
* <text class="title|sub|mono|heading [info|good|warn|bad]"> text roles; text-anchor stays an attribute
* .edge.dashed an answer or a nudge, not a main flow
* figure.diagram.wide svg at least 1000px wide, scrolls sideways on a phone
* an svg may also use currentColor and var(--good|--bad|--warn|--accent) in fill and stroke attributes
*/
figure {
margin-left: 0;
margin-right: 0;
}
figure.diagram {
background: var(--card);
border: 1px solid var(--border);
border-radius: var(--radius);
padding: 14px;
overflow-x: auto;
color: var(--foreground);
}
figure.diagram svg {
display: block;
width: 100%;
height: auto;
min-width: 640px;
font-family: var(--font-mono);
}
figure.diagram.wide svg {
min-width: 1000px;
}
figure.diagram text {
fill: var(--foreground);
}
figcaption {
color: var(--muted-foreground);
font-size: 13px;
margin-top: 8px;
}
.node rect,
.node circle,
.node ellipse,
.node polygon {
fill: var(--card);
stroke: var(--muted-foreground);
stroke-width: 1;
}
.node.accent rect,
.node.accent circle,
.node.accent polygon {
fill: var(--accent-bg);
stroke: var(--accent);
stroke-width: 1.5;
}
.node.dashed rect,
.node.dashed circle,
.node.dashed polygon {
stroke-dasharray: 5 4;
}
.node.good rect {
fill: var(--good-bg);
stroke: var(--good);
}
.node.bad rect {
fill: var(--bad-bg);
stroke: var(--bad);
}
.node.warn rect {
fill: var(--warn-bg);
stroke: var(--warn);
}
.node text {
fill: var(--foreground);
font: 500 14px var(--font-mono);
text-anchor: middle;
}
.node text.sub {
fill: var(--muted-foreground);
font: 400 11px var(--font-mono);
}
.edge {
fill: none;
stroke: var(--muted-foreground);
stroke-width: 1.4;
}
.arrow {
fill: var(--muted-foreground);
}
.edge-label {
fill: var(--muted-foreground);
font: 400 11px var(--font-mono);
text-anchor: middle;
paint-order: stroke;
stroke: var(--card);
stroke-width: 4px;
stroke-linejoin: round;
}
.edge.back {
stroke: var(--accent);
stroke-dasharray: 5 4;
}
.arrow.back,
.edge-label.back {
fill: var(--accent);
}
.edge.good {
stroke: var(--good);
}
.arrow.good,
.edge-label.good {
fill: var(--good);
}
.edge.bad {
stroke: var(--bad);
}
.arrow.bad,
.edge-label.bad {
fill: var(--bad);
}
.edge.warn {
stroke: var(--warn);
}
.arrow.warn,
.edge-label.warn {
fill: var(--warn);
}
.group {
fill: none;
stroke: var(--muted-foreground);
stroke-opacity: 0.5;
stroke-dasharray: 5 3;
}
.group-label {
fill: var(--muted-foreground);
font: 500 11px var(--font-mono);
}
/* shapes with their own classes, for drawings that place their own text */
svg .box {
fill: var(--card);
stroke: var(--muted-foreground);
stroke-width: 1.2;
}
svg .box.info {
fill: color-mix(in srgb, var(--blue) 14%, var(--card));
stroke: var(--blue);
}
svg .box.good {
fill: color-mix(in srgb, var(--green) 14%, var(--card));
stroke: var(--green);
}
svg .box.warn {
fill: color-mix(in srgb, var(--yellow) 18%, var(--card));
stroke: var(--yellow);
}
svg .box.bad {
fill: color-mix(in srgb, var(--red) 14%, var(--card));
stroke: var(--red);
}
svg .box.accent {
fill: color-mix(in srgb, var(--orange) 14%, var(--card));
stroke: var(--orange);
}
svg .box.strong {
stroke: var(--foreground);
stroke-width: 1.6;
}
svg .box.dashed,
svg .edge.dashed {
stroke-dasharray: 5 4;
}
svg .box.open {
fill: none;
}
svg .zone {
fill: color-mix(in srgb, var(--muted-foreground) 6%, transparent);
stroke: var(--muted-foreground);
stroke-width: 1.5;
stroke-dasharray: 7 5;
}
svg .zone.info {
fill: color-mix(in srgb, var(--blue) 7%, transparent);
}
svg .zone.good {
fill: color-mix(in srgb, var(--green) 7%, transparent);
}
svg .zone.warn {
fill: color-mix(in srgb, var(--yellow) 9%, transparent);
}
svg .zone.bad {
fill: color-mix(in srgb, var(--red) 6%, transparent);
}
svg .zone.accent {
fill: color-mix(in srgb, var(--orange) 7%, transparent);
}
svg .zone.boundary {
stroke: var(--red);
}
svg .panel {
fill: color-mix(in srgb, var(--foreground) 4%, transparent);
stroke: var(--border);
}
svg .chip {
fill: var(--blue);
}
svg .chip.good {
fill: var(--green);
}
svg .chip.accent {
fill: var(--orange);
}
svg text.chip-text {
fill: var(--background);
font: 700 10px var(--font-mono);
}
svg .fill {
fill: var(--card);
stroke: none;
}
svg .line {
fill: none;
stroke: var(--foreground);
stroke-width: 1.6;
}
svg .rule {
stroke: var(--border);
stroke-width: 1.5;
stroke-dasharray: 3 5;
}
svg text.title {
fill: var(--foreground);
font: 600 13px var(--font-mono);
}
svg text.sub {
fill: var(--muted-foreground);
font: 400 11px var(--font-mono);
}
svg text.mono {
fill: var(--muted-foreground);
font: 400 10.5px var(--font-mono);
}
svg text.heading {
fill: var(--muted-foreground);
font: 600 11px var(--font-mono);
letter-spacing: 0.06em;
text-transform: uppercase;
}
svg text.info {
fill: var(--info);
}
svg text.good {
fill: var(--good);
}
svg text.warn {
fill: var(--warn);
}
svg text.bad {
fill: var(--bad);
}
/* index */
.index-head h1 {
font-size: 26px;
}
.index-head p {
margin: 4px 0 0;
color: var(--muted-foreground);
font-size: 13px;
}
.index h2 {
display: flex;
align-items: baseline;
gap: 8px;
font-size: 13px;
font-weight: 600;
letter-spacing: 0.06em;
text-transform: uppercase;
color: var(--muted-foreground);
margin: 36px 0 6px;
padding: 0;
border: 0;
}
.index h2 .count {
font: 500 12px var(--font-mono);
letter-spacing: 0;
}
.rows {
list-style: none;
padding: 0;
margin: 0;
background: var(--card);
border: 1px solid var(--border);
border-radius: var(--radius);
}
.rows li {
display: grid;
grid-template-columns: 52px minmax(0, 1fr) auto;
gap: 12px;
align-items: baseline;
padding: 9px 14px;
margin: 0;
}
.rows li + li {
border-top: 1px solid var(--border);
}
.rows .id {
font: 500 12px var(--font-mono);
color: var(--muted-foreground);
}
.rows .meta {
font-size: 12px;
color: var(--muted-foreground);
white-space: nowrap;
}
.rows .title.superseded a {
color: var(--muted-foreground);
}
.rows.plain li {
grid-template-columns: minmax(0, 1fr);
}
.empty {
color: var(--muted-foreground);
font-size: 13px;
margin: 0;
}
@media (max-width: 560px) {
.rows li {
grid-template-columns: 44px minmax(0, 1fr);
}
.rows .meta {
grid-column: 2;
}
}
/* a page rendered from markdown */
.md-meta {
display: flex;
flex-wrap: wrap;
gap: 4px 16px;
font-size: 13px;
color: var(--muted-foreground);
margin: 12px 0 0;
}
.md-meta dt {
display: inline;
font-weight: 500;
}
.md-meta dd {
display: inline;
margin: 0 0 0 4px;
}
.md-meta div {
min-width: 0;
}
.files {
font-size: 13px;
color: var(--muted-foreground);
margin-top: 32px;
padding-top: 16px;
border-top: 1px solid var(--border);
}
/* serve's hub: one row per project */
.rows.hub li {
grid-template-columns: minmax(0, 1fr) auto;
}
@media (max-width: 560px) {
.rows.hub li {
grid-template-columns: minmax(0, 1fr);
}
.rows.hub .meta {
grid-column: 1;
}
}
/* serve's search */
form.search,
input.filter {
margin: 24px 0 0;
}
form.search input,
input.filter {
width: 100%;
font: inherit;
color: var(--foreground);
background: var(--card);
border: 1px solid var(--input);
border-radius: var(--radius);
padding: 9px 14px;
}
form.search input:focus,
input.filter:focus {
outline: 2px solid var(--blue);
outline-offset: 1px;
}
.rows.results li {
grid-template-columns: 52px minmax(0, 1fr);
}
.rows.results .meta {
display: none;
}
.snippet {
display: block;
font-size: 13px;
color: var(--muted-foreground);
margin-top: 2px;
}
mark {
background: var(--warn-bg);
color: inherit;
border-radius: 3px;
padding: 0 2px;
}

844
claude/skills/notes/notes.py Executable file
View File

@@ -0,0 +1,844 @@
#!/usr/bin/env python3
"""mechanics for a project's .notes/ dir, see ~/.config/claude/rules/notes.md
usage:
notes.py [--root DIR] init create .notes/ with its git repo, if missing
notes.py [--root DIR] next d|w|q print the next free id of a bucket
notes.py [--root DIR] index regenerate index.html, notes.css, the markdown pages and
the portable copies of other/out/ in _out/
notes.py [--root DIR] commit SUBJECT regenerate the index, commit every change in .notes/
notes.py serve [--port 8765] [--roots DIR ...]
every project's notes on one port; roots default to
$NOTES_ROOTS, else ~/git
DIR is the project root, by default the git toplevel of the current dir, else the current dir
"""
import argparse
import html
import re
import subprocess
import sys
from datetime import datetime
from pathlib import Path
from urllib.parse import quote
BUCKETS = {"d": "docs", "w": "work", "q": "questions"}
ID_RE = re.compile(r"^(docs|work|questions)/([dwq])(\d{3})-")
README = (
"Local notes, never pushed. Layout and rules: ~/.config/claude/rules/notes.md\n"
)
def git(notes: Path, *args: str, check: bool = True) -> str:
return subprocess.run(
["git", "-C", str(notes), *args], check=check, capture_output=True, text=True
).stdout
def project_root(arg: str | None) -> Path:
if arg:
return Path(arg).resolve()
out = subprocess.run(
["git", "rev-parse", "--show-toplevel"],
check=False,
capture_output=True,
text=True,
)
root = Path(out.stdout.strip()) if out.returncode == 0 else Path.cwd()
# inside .notes the toplevel is the notes repo itself
return root.parent if root.name == ".notes" else root
def init(notes: Path) -> None:
for d in ("docs", "work", "questions", "other/in", "other/out"):
(notes / d).mkdir(parents=True, exist_ok=True)
if not (notes / "README.md").exists():
(notes / "README.md").write_text(README)
if not (notes / ".gitignore").exists():
(notes / ".gitignore").write_text("/index.html\n")
if not (notes / ".git").exists():
git(notes, "init", "-q", "-b", "main")
# NOTE:(@janezicmatej) local-only repo, any identity works when none is configured
if not git(notes, "config", "user.email", check=False).strip():
git(notes, "config", "user.name", "notes")
git(notes, "config", "user.email", "notes@localhost")
commit(notes, "init notes")
else:
write_index(notes)
print(notes)
def next_id(notes: Path, letter: str) -> str:
bucket = BUCKETS[letter]
paths = [f"{bucket}/{p.name}" for p in (notes / bucket).glob("*")]
if (notes / ".git").exists():
log = git(notes, "log", "--all", "--name-only", "--pretty=format:", check=False)
paths += log.splitlines()
nums = [int(m[3]) for p in paths if (m := ID_RE.match(p)) and m[2] == letter]
return f"{letter}{max(nums, default=0) + 1:03d}"
def commit(notes: Path, subject: str) -> None:
write_index(notes)
git(notes, "add", "-A")
if git(notes, "status", "--porcelain").strip():
git(notes, "commit", "-q", "--no-gpg-sign", "-m", subject)
print(git(notes, "log", "-1", "--oneline").strip())
else:
print("nothing to commit")
# pages: index.html, notes.css, _pages/ and _out/ are generated, never committed
CSS = Path(__file__).with_name("notes.css")
GENERATED = ("/index.html", "/notes.css", "/_pages/", "/_out/")
PAGES = "_pages"
OUT = "_out"
CSS_LINK = re.compile(r'<link\b[^>]*href="[^"]*notes\.css"[^>]*>', re.IGNORECASE)
BACK_NAV = re.compile(r'\s*<nav class="back">.*?</nav>', re.DOTALL | re.IGNORECASE)
ID_TOKEN = re.compile(r"(?<![\w/.-])([dwq]\d{3})(?![\w/-])")
def ensure_gitignore(notes: Path) -> None:
path = notes / ".gitignore"
lines = path.read_text().splitlines() if path.exists() else []
missing = [g for g in GENERATED if g not in lines]
if missing:
path.write_text("\n".join([*lines, *missing]) + "\n")
def frontmatter(text: str) -> tuple[dict[str, str], str]:
m = re.match(r"^---\n(.*?)\n---\n?", text, re.DOTALL)
if not m:
return {}, text
meta = {}
for line in m[1].splitlines():
key, sep, value = line.partition(":")
if sep:
meta[key.strip()] = value.strip()
return meta, text[m.end() :]
def split_title(body: str, fallback: str) -> tuple[str, str]:
"""first heading as the title, without a leading id, and the body without it"""
m = re.search(r"^#\s+(.+)\n?", body, re.MULTILINE)
if not m:
return fallback, body
title = re.sub(r"^[dwq]\d{3}\b\s*", "", m[1].strip())
return title, body[: m.start()] + body[m.end() :]
def strip_tags(s: str) -> str:
return html.unescape(re.sub(r"<[^>]+>", "", s)).strip()
class Site:
"""what exists in .notes/ and where each item's page is, relative to .notes/"""
def __init__(self, notes: Path) -> None:
self.notes = notes
self.docs = self._docs()
self.work = sorted(p for p in (notes / "work").glob("w[0-9]*") if p.is_dir())
self.questions = sorted((notes / "questions").glob("q[0-9]*.md"))
self.other = {
sub: sorted(f for f in (notes / "other" / sub).rglob("*") if f.is_file())
for sub in ("in", "out")
if (notes / "other" / sub).exists()
}
self.urls: dict[str, str] = {}
for d in self.docs:
self.urls[d["id"]] = d["page"]
for w in self.work:
self.urls[w.name[:4]] = self.page_of(w / "brief.md")
for q in self.questions:
self.urls[q.name[:4]] = self.page_of(q)
def _docs(self) -> list[dict]:
out = []
for p in sorted((self.notes / "docs").glob("d[0-9]*")):
page = p / "index.html" if p.is_dir() else p
if not page.is_file() or page.suffix != ".html":
continue
text = page.read_text(errors="replace")
title = re.search(r"<title>(.*?)</title>", text, re.DOTALL | re.IGNORECASE)
status = re.search(
r"<p[^>]*class=\"[^\"]*\bstatus\b[^\"]*\"[^>]*>(.*?)</p>",
text,
re.DOTALL | re.IGNORECASE,
)
status_text = re.sub(
r"^status:\s*", "", strip_tags(status[1]) if status else ""
)
out.append(
{
"id": p.name[:4],
"title": strip_tags(title[1]) if title else p.stem,
"page": page.relative_to(self.notes).as_posix(),
"status": status_text,
}
)
return out
def page_of(self, src: Path) -> str:
"""where a markdown file's rendered page lives, relative to .notes/"""
rel = src.relative_to(self.notes).with_suffix(".html")
return f"{PAGES}/{rel.as_posix()}"
def href(self, target: str, from_page: str) -> str:
"""a link from one page to another, both relative to .notes/"""
base = Path(from_page).parent
return quote(Path(*([".."] * len(base.parts)), target).as_posix())
def status_tag(status: str) -> str:
e = html.escape
if status.startswith("current"):
return f'<span class="tag good" title="{e(status)}">current</span>'
if status.startswith("partly stale"):
return f'<span class="tag warn" title="{e(status)}">stale</span>'
if m := re.match(r"superseded by (d\d{3})", status):
return f'<span class="tag" title="{e(status)}">superseded by {m[1]}</span>'
return '<span class="tag bad">no status line</span>'
def page(site: Site, path: str, title: str, body: str) -> str:
css = site.href("notes.css", path)
return (
'<!doctype html>\n<html lang="en">\n<head>\n<meta charset="utf-8">\n'
'<meta name="viewport" content="width=device-width, initial-scale=1">\n'
f"<title>{html.escape(title)}</title>\n"
f'<link rel="stylesheet" href="{css}">\n</head>\n'
f'<body>\n<main class="page">\n{body}\n</main>\n</body>\n</html>\n'
)
# markdown, the small subset notes are written in
def inline(text: str, site: Site, at: str) -> str:
out, last = [], 0
for m in re.finditer(r"`([^`]+)`", text):
out.append(inline_plain(text[last : m.start()], site, at))
out.append(f"<code>{html.escape(m[1])}</code>")
last = m.end()
out.append(inline_plain(text[last:], site, at))
return "".join(out)
def inline_plain(text: str, site: Site, at: str) -> str:
links: list[str] = []
def keep(s: str) -> str:
links.append(s)
return f"\x00{len(links) - 1}\x00"
text = re.sub(
r"\[([^\]]+)\]\(([^)\s]+)\)",
lambda m: keep(f'<a href="{html.escape(m[2])}">{html.escape(m[1])}</a>'),
text,
)
text = html.escape(text, quote=False)
text = re.sub(r"\*\*(.+?)\*\*", r"<strong>\1</strong>", text)
def id_link(m: re.Match) -> str:
url = site.urls.get(m[1])
return f'<a href="{site.href(url, at)}">{m[1]}</a>' if url else m[1]
text = ID_TOKEN.sub(id_link, text)
return re.sub(r"\x00(\d+)\x00", lambda m: links[int(m[1])], text)
# gfm pipe tables: a header row, a row of dashes, then body rows up to a line without a pipe
PIPE = re.compile(r"(?<!\\)\|")
SEPARATOR_CELL = re.compile(r"^:?-+:?$")
ALIGN = {(True, True): "center", (False, True): "right", (True, False): "left"}
def table_cells(line: str) -> list[str]:
s = line.strip()
s = s.removeprefix("|")
s = s[:-1] if s.endswith("|") and not s.endswith("\\|") else s
return [c.strip().replace("\\|", "|") for c in PIPE.split(s)]
def table_start(lines: list[str], i: int) -> list[str] | None:
"""the column alignments if a table starts at lines[i], else None"""
if i + 1 >= len(lines) or not (PIPE.search(lines[i]) and PIPE.search(lines[i + 1])):
return None
seps = table_cells(lines[i + 1])
if len(table_cells(lines[i])) != len(seps):
return None
if not all(SEPARATOR_CELL.match(c) for c in seps):
return None
return [ALIGN.get((c[0] == ":", c[-1] == ":"), "") for c in seps]
def table_row(line: str, aligns: list[str], tag: str, site: Site, at: str) -> str:
# short rows are padded, extra cells dropped, as gfm does
cells = (table_cells(line) + [""] * len(aligns))[: len(aligns)]
row = []
for cell, align in zip(cells, aligns):
style = f' style="text-align: {align}"' if align else ""
row.append(f"<{tag}{style}>{inline(cell, site, at)}</{tag}>")
return f"<tr>{''.join(row)}</tr>"
def markdown(text: str, site: Site, at: str) -> str:
lines = text.splitlines()
out: list[str] = []
para: list[str] = []
# open lists as (indent, tag)
lists: list[tuple[int, str]] = []
item_open = False
def flush_para() -> None:
if para:
out.append(f"<p>{inline(' '.join(para), site, at)}</p>")
para.clear()
def close_lists(to: int = -1) -> None:
nonlocal item_open
while lists and lists[-1][0] > to:
out.append(f"</li></{lists.pop()[1]}>")
item_open = bool(lists)
i = 0
while i < len(lines):
line = lines[i]
if line.lstrip().startswith("```"):
flush_para()
close_lists()
indent = len(line) - len(line.lstrip())
code = []
i += 1
while i < len(lines) and not lines[i].lstrip().startswith("```"):
code.append(lines[i][indent:])
i += 1
out.append(f"<pre><code>{html.escape(chr(10).join(code))}</code></pre>")
i += 1
continue
if not line.strip():
flush_para()
i += 1
continue
if m := re.match(r"^(#{1,4})\s+(.*)$", line):
flush_para()
close_lists()
level = min(len(m[1]) + 1, 4)
out.append(f"<h{level}>{inline(m[2], site, at)}</h{level}>")
i += 1
continue
if aligns := table_start(lines, i):
flush_para()
close_lists()
head = table_row(line, aligns, "th", site, at)
i += 2
body = []
while i < len(lines) and PIPE.search(lines[i]):
body.append(table_row(lines[i], aligns, "td", site, at))
i += 1
tbody = f"<tbody>{''.join(body)}</tbody>" if body else ""
out.append(
f'<div class="table"><table><thead>{head}</thead>{tbody}</table></div>'
)
continue
if m := re.match(r"^(\s*)([-*]|\d+\.)\s+(.*)$", line):
flush_para()
indent, tag = len(m[1]), "ol" if m[2][0].isdigit() else "ul"
if not lists or indent > lists[-1][0]:
out.append(f"<{tag}><li>")
lists.append((indent, tag))
else:
close_lists(indent)
# the other kind of list at the same indent ends this one and starts its own
if lists and lists[-1][0] == indent and lists[-1][1] != tag:
close_lists(indent - 1)
if lists and lists[-1][0] == indent:
out.append("</li><li>")
else:
out.append(f"<{tag}><li>")
lists.append((indent, tag))
item = [m[3]]
i += 1
# continuation lines belong to the item
while (
i < len(lines)
and lines[i].strip()
and not re.match(r"^\s*([-*]|\d+\.)\s+|^\s*```|^#{1,4}\s", lines[i])
and not table_start(lines, i)
):
item.append(lines[i].strip())
i += 1
out.append(inline(" ".join(item), site, at))
continue
if lists and line.startswith(" "):
out.append(" " + inline(line.strip(), site, at))
i += 1
continue
close_lists()
para.append(line.strip())
i += 1
flush_para()
close_lists()
return "\n".join(out)
def render_md(site: Site, src: Path, kind: str) -> None:
at = site.page_of(src)
meta, body = frontmatter(src.read_text(errors="replace"))
title, body = split_title(body, src.stem)
e = html.escape
item_id = next((p[:4] for p in src.parts if re.match(r"[dwq]\d{3}-", p)), "")
eyebrow = " · ".join(x for x in (item_id, kind) if x)
parts = [
f'<nav class="back"><a href="{site.href("index.html", at)}">← notes</a></nav>',
"<header>",
f'<p class="eyebrow">{e(eyebrow)}</p>' if eyebrow else "",
f"<h1>{e(title)}</h1>",
]
if meta:
dl = "".join(
f"<div><dt>{e(k)}</dt><dd>{inline(v, site, at)}</dd></div>"
for k, v in meta.items()
)
parts.append(f'<dl class="md-meta">{dl}</dl>')
parts += ["</header>", markdown(body, site, at)]
if kind == "work":
files = []
for f in sorted(src.parent.rglob("*")):
if not f.is_file() or f == src:
continue
target = site.page_of(f) if f.suffix == ".md" else f.relative_to(site.notes)
files.append(f'<a href="{site.href(str(target), at)}">{e(f.name)}</a>')
if files:
parts.append(f'<p class="files">files: {" · ".join(files)}</p>')
out = site.notes / at
out.parent.mkdir(parents=True, exist_ok=True)
out.write_text(page(site, at, title, "\n".join(p for p in parts if p)))
def clear(d: Path) -> None:
if d.exists():
for f in sorted(d.rglob("*"), reverse=True):
f.unlink() if f.is_file() else f.rmdir()
def write_portable(site: Site) -> None:
"""other/out/ as it leaves .notes/: css inlined, no back link to an index it won't have"""
out = site.notes / OUT
clear(out)
src = site.notes / "other" / "out"
style = f"<style>\n{CSS.read_text()}</style>"
for f in site.other.get("out", []):
target = out / f.relative_to(src)
target.parent.mkdir(parents=True, exist_ok=True)
if f.suffix != ".html":
target.write_bytes(f.read_bytes())
continue
# the nav goes before the css comes in: its header comment shows a nav too
text = BACK_NAV.sub("", f.read_text(errors="replace"), count=1)
target.write_text(CSS_LINK.sub(lambda _: style, text, count=1))
def write_index(notes: Path) -> None:
ensure_gitignore(notes)
(notes / "notes.css").write_text(CSS.read_text())
site = Site(notes)
clear(notes / PAGES)
write_portable(site)
for q in site.questions:
render_md(site, q, "question")
for w in site.work:
for f in sorted(w.rglob("*.md")):
render_md(site, f, "work")
for files in site.other.values():
for f in files:
if f.suffix == ".md":
render_md(site, f, "other")
e = html.escape
def section(name: str, rows: list[str], empty: str, plain: bool = False) -> str:
head = f'<h2>{name} <span class="count">{len(rows)}</span></h2>'
if not rows:
return f'{head}<p class="empty">{empty}</p>'
cls = "rows plain" if plain else "rows"
return f'{head}<ul class="{cls}">{"".join(rows)}</ul>'
def row(item_id: str, href: str, title: str, meta: str = "", cls: str = "") -> str:
return (
f'<li><span class="id">{e(item_id)}</span>'
f'<span class="title {cls}"><a href="{href}">{e(title)}</a></span>'
f'<span class="meta">{meta}</span></li>'
)
docs = [
row(
d["id"],
quote(d["page"]),
d["title"],
status_tag(d["status"]),
"superseded" if d["status"].startswith("superseded") else "",
)
for d in site.docs
]
work = []
for w in site.work:
brief = w / "brief.md"
title = w.name[5:]
if brief.exists():
title, _ = split_title(frontmatter(brief.read_text())[1], title)
work.append(row(w.name[:4], quote(site.urls[w.name[:4]]), title))
questions = []
for q in site.questions:
meta, body = frontmatter(q.read_text(errors="replace"))
title, _ = split_title(body, q.stem)
created = e(meta.get("created", ""))
questions.append(row(q.name[:4], quote(site.page_of(q)), title, created))
other = []
for sub, files in site.other.items():
for f in files:
target = site.page_of(f) if f.suffix == ".md" else f.relative_to(notes)
portable = ""
if sub == "out" and f.suffix == ".html":
rel = f.relative_to(notes / "other" / "out").as_posix()
portable = (
f' <a class="tag info" href="{quote(f"{OUT}/{rel}")}">to send</a>'
)
other.append(
f'<li><span class="title"><a href="{quote(str(target))}">{e(f.name)}</a>'
f' <span class="tag">{sub}</span>{portable}</span></li>'
)
project = notes.parent.name
body = "\n".join(
[
# under serve this is the hub, under a plain http.server it is this index
'<nav class="back"><a href="/">← all notes</a></nav>',
'<header class="index-head">',
f"<h1>{e(project)} notes</h1>",
(
f"<p>{len(site.docs)} docs · {len(site.work)} in flight · "
f"{len(site.questions)} open questions · generated {datetime.now().astimezone().date()}</p>"
),
"</header>",
'<div class="index">',
section("Docs", docs, "no docs"),
section("Work in flight", work, "nothing in flight"),
section("Open questions", questions, "no open questions"),
section("Other", other, "nothing here", plain=True) if other else "",
"</div>",
]
)
(notes / "index.html").write_text(
page(site, "index.html", f"{project} notes", body)
)
# serve: every project's notes on one port
SKIP_DIRS = {"node_modules", "target", "dist", "build", "vendor", "__pycache__"}
def find_notes(roots: list[Path], depth: int = 6) -> dict[str, Path]:
"""url prefix (path relative to its root) -> .notes dir, for every project under roots"""
found: dict[str, Path] = {}
def walk(d: Path, root: Path, left: int) -> None:
notes = d / ".notes"
if notes.is_dir() and (notes / "docs").is_dir():
# a root that is itself a project goes by its name, not "."
found[d.name if d == root else d.relative_to(root).as_posix()] = notes
# a project's subdirectories are its code, even when the project is a root
return
# a repo's own subdirectories are its code, not more projects
if left == 0 or ((d / ".git").exists() and d != root):
return
try:
children = sorted(d.iterdir())
except OSError:
return
for c in children:
skip = c.name.startswith(".") or c.name in SKIP_DIRS
if c.is_dir() and not c.is_symlink() and not skip:
walk(c, root, left - 1)
for root in roots:
if root.is_dir():
walk(root, root, depth)
return found
def hub_page(title: str, body: str) -> str:
return (
'<!doctype html>\n<html lang="en">\n<head>\n<meta charset="utf-8">\n'
'<meta name="viewport" content="width=device-width, initial-scale=1">\n'
f"<title>{html.escape(title)}</title>\n"
'<link rel="stylesheet" href="/notes.css">\n</head>\n'
f'<body>\n<main class="page">\n{body}\n</main>\n</body>\n</html>\n'
)
def search_form(action: str, q: str = "") -> str:
return (
f'<form class="search" action="{action}" role="search">'
f'<input type="search" name="q" value="{html.escape(q)}" '
'placeholder="search this project\'s notes" aria-label="search notes">'
"</form>"
)
# filters the hub's project rows as you type, nothing leaves the page
FILTER_BOX = (
'<input class="filter" type="search" placeholder="filter projects" '
'aria-label="filter projects" autofocus>'
)
FILTER_SCRIPT = """<script>
const box = document.querySelector("input.filter");
const rows = [...document.querySelectorAll(".rows.hub li")];
box.addEventListener("input", () => {
const words = box.value.toLowerCase().split(/\\s+/).filter(Boolean);
for (const r of rows) {
const name = r.dataset.name;
r.hidden = !words.every((w) => name.includes(w));
}
document.querySelector(".hub-empty").hidden = rows.some((r) => !r.hidden);
});
box.addEventListener("keydown", (e) => {
const first = rows.find((r) => !r.hidden);
if (e.key === "Enter" && first) location.href = first.querySelector("a").href;
});
</script>"""
def hub(projects: dict[str, Path]) -> str:
e = html.escape
rows = []
for prefix, notes in sorted(projects.items()):
questions = len(list((notes / "questions").glob("q[0-9]*.md")))
work = len([p for p in (notes / "work").glob("w[0-9]*") if p.is_dir()])
docs = len(list((notes / "docs").glob("d[0-9]*")))
last = git(notes, "log", "-1", "--format=%cs", check=False).strip()
meta = f"{docs} docs · {work} in flight · {questions} open · {last or 'no commits'}"
rows.append(
f'<li data-name="{e(prefix.lower())}">'
f'<span class="title"><a href="/{quote(prefix)}/">{e(prefix)}</a></span>'
f'<span class="meta">{meta}</span></li>'
)
body = (
'<header class="index-head"><h1>notes</h1>'
f"<p>{len(projects)} projects · generated {datetime.now().astimezone().date()}</p></header>"
+ (FILTER_BOX if rows else "")
+ '<div class="index"><h2>Projects</h2>'
+ (
f'<ul class="rows hub">{"".join(rows)}</ul>'
'<p class="empty hub-empty" hidden>no project matches</p>'
if rows
else '<p class="empty">no .notes/ found</p>'
)
+ "</div>"
# after the rows, so the script finds them
+ (FILTER_SCRIPT if rows else "")
)
return hub_page("notes", body)
def page_text(page: str) -> str:
"""the readable text of an html page, without its chrome, words kept apart"""
flags = re.DOTALL | re.IGNORECASE
page = re.sub(r"<(style|script|svg|nav|title)\b.*?</\1>", " ", page, flags=flags)
return html.unescape(re.sub(r"<[^>]+>", " ", page))
def searchable(notes: Path) -> list[tuple[str, str, str, str]]:
"""(id, title, url relative to .notes/, plain text) for every page worth searching"""
site = Site(notes)
out = []
for d in site.docs:
text = (notes / d["page"]).read_text(errors="replace")
out.append((d["id"], d["title"], d["page"], page_text(text)))
mds = [*site.questions, *(f for w in site.work for f in sorted(w.rglob("*.md")))]
mds += [f for files in site.other.values() for f in files if f.suffix == ".md"]
for f in mds:
_, body = frontmatter(f.read_text(errors="replace"))
title, _ = split_title(body, f.stem)
item = next((p[:4] for p in f.parts if re.match(r"[dwq]\d{3}-", p)), "")
out.append((item, title, site.page_of(f), body))
for files in site.other.values():
for f in files:
if f.suffix == ".html":
text = page_text(f.read_text(errors="replace"))
out.append(("", f.name, f.relative_to(notes).as_posix(), text))
return out
def search(prefix: str, notes: Path, q: str) -> str:
e = html.escape
terms = [t.lower() for t in q.split() if t]
hits = []
for item, title, url, text in searchable(notes) if terms else []:
low_title, low = title.lower(), " ".join(text.split()).lower()
if not all(t in low_title or t in low for t in terms):
continue
flat = " ".join(text.split())
# centre on the whole phrase if it occurs, else on the rarest word
at = low.find(" ".join(terms))
if at < 0:
rarest = min((t for t in terms if t in low), key=low.count, default="")
at = max(low.find(rarest), 0) if rarest else 0
start = max(0, at - 80)
snippet = e(("…" if start else "") + flat[start : at + 160] + "…")
for t in sorted(set(terms), key=len, reverse=True):
snippet = re.sub(
f"({re.escape(e(t))})", r"<mark>\1</mark>", snippet, flags=re.IGNORECASE
)
score = sum(t in low_title for t in terms) * 100 + sum(
low.count(t) for t in terms
)
hits.append((score, item, title, url, snippet))
write_index(notes)
hits.sort(key=lambda h: -h[0])
rows = "".join(
f'<li><span class="id">{e(item)}</span><span class="title">'
f'<a href="{quote(url)}">{e(title)}</a>'
f'<span class="snippet">{snippet}</span></span></li>'
for _, item, title, url, snippet in hits
)
found = (
f'<ul class="rows results">{rows}</ul>'
if rows
else '<p class="empty">nothing found</p>'
)
body = (
'<nav class="back"><a href="./">← notes</a></nav>'
f'<header class="index-head"><h1>{e(prefix)}: search</h1>'
f"<p>{len(hits)} results for “{e(q)}”</p></header>"
+ search_form("search", q)
+ f'<div class="index">{found}</div>'
)
return hub_page(f"{q} · {prefix} notes", body)
def serve(roots: list[Path], host: str, port: int) -> None:
import http.server
from urllib.parse import parse_qs, unquote, urlsplit
class Handler(http.server.SimpleHTTPRequestHandler):
def guess_type(self, path: str) -> str:
if str(path).endswith(".md"):
return "text/plain; charset=utf-8"
return super().guess_type(path)
def send_text(self, body: str, ctype: str) -> None:
data = body.encode()
self.send_response(200)
self.send_header("Content-Type", ctype)
self.send_header("Content-Length", str(len(data)))
self.send_header("Cache-Control", "no-cache")
self.end_headers()
self.wfile.write(data)
def do_GET(self) -> None:
path = unquote(urlsplit(self.path).path)
if path in ("/", "/index.html"):
return self.send_text(
hub(find_notes(roots)), "text/html; charset=utf-8"
)
if path == "/notes.css":
return self.send_text(CSS.read_text(), "text/css; charset=utf-8")
projects = find_notes(roots)
prefix = max(
(p for p in projects if path == f"/{p}" or path.startswith(f"/{p}/")),
key=len,
default=None,
)
if prefix is None:
return self.send_error(404, "no such project")
if path == f"/{prefix}":
self.send_response(301)
self.send_header("Location", f"/{quote(prefix)}/")
self.end_headers()
return None
rest = path[len(prefix) + 2 :]
notes = projects[prefix]
if rest == "search":
q = parse_qs(urlsplit(self.path).query).get("q", [""])[0]
body = search(prefix, notes, q)
return self.send_text(body, "text/html; charset=utf-8")
if rest in ("", "index.html"):
# rebuilt on every visit, so a session that forgot to regenerate never shows stale;
# the search box only works under serve, so it is added here, not in the file
write_index(notes)
page = (notes / "index.html").read_text()
page = page.replace("</header>", "</header>" + search_form("search"), 1)
return self.send_text(page, "text/html; charset=utf-8")
self.serve_from = projects[prefix]
self.path = "/" + rest
return super().do_GET()
def translate_path(self, path: str) -> str:
base = self.serve_from.resolve()
target = (base / unquote(urlsplit(path).path).lstrip("/")).resolve()
return str(target if target.is_relative_to(base) else base / "__outside__")
def log_message(self, format: str, *args) -> None:
pass
server = http.server.ThreadingHTTPServer((host, port), Handler)
print(f"serving notes from {', '.join(map(str, roots))} on http://{host}:{port}/")
try:
server.serve_forever()
except KeyboardInterrupt:
pass
def default_roots() -> list[Path]:
import os
env = os.environ.get("NOTES_ROOTS")
if env:
return [Path(p).expanduser() for p in env.split(os.pathsep) if p]
return [Path.home() / "git"]
def main() -> None:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--root")
sub = parser.add_subparsers(dest="cmd", required=True)
sub.add_parser("init")
p_next = sub.add_parser("next")
p_next.add_argument("letter", choices=sorted(BUCKETS))
sub.add_parser("index")
p_commit = sub.add_parser("commit")
p_commit.add_argument("subject")
p_serve = sub.add_parser("serve")
p_serve.add_argument("--port", type=int, default=8765)
p_serve.add_argument("--host", default="127.0.0.1")
p_serve.add_argument("--roots", nargs="*", type=Path)
args = parser.parse_args()
if args.cmd == "serve":
serve(args.roots or default_roots(), args.host, args.port)
return
notes = project_root(args.root) / ".notes"
if args.cmd == "init":
init(notes)
return
if not notes.exists():
sys.exit(f"{notes} does not exist, run init first")
if args.cmd == "next":
print(next_id(notes, args.letter))
elif args.cmd == "index":
write_index(notes)
print(notes / "index.html")
elif args.cmd == "commit":
commit(notes, args.subject)
if __name__ == "__main__":
main()

4
git/config
View File

@@ -47,6 +47,10 @@
[alias]
blame-ignore = "config blame.ignoreRevsFile .git-blame-ignore-revs"
# re-sign <upstream>..<branch> as the repo identity, keeping trees and merge topology
sign-branch = "!~/.config/bin/git-sign-branch --reset-author"
# list every commit in <range> without a good signature; exits 1 if any, git's status if the range is bad
check-signed = "!f() { log=$(git log --format='%G? %h %s' \"${1:-main..HEAD}\") || exit; bad=$(printf '%s\\n' \"$log\" | grep -v -e '^[GU] ' -e '^$'); [ -z \"$bad\" ] && echo 'all signed' || { printf '%s\\n' \"$bad\"; exit 1; }; }; f"
[branch]
sort = -committerdate

1
git/ignore
View File

@@ -9,6 +9,7 @@
# ai
CLAUDE.local.md
.claude
.notes
# languages
.python-version

10
zsh/.zshrc
View File

@@ -91,6 +91,16 @@ fi
zstyle ':completion:*' cache-path "$XDG_CACHE_HOME/zsh/zcompcache"
zstyle ':completion:*' menu select
zstyle ':completion:*' matcher-list 'm:{a-z}={A-Z}'
# _git picks these up for the matching git aliases (git/config)
_git-sign-branch() {
_arguments \
'(-n --dry-run)'{-n,--dry-run}'[list the commits that would be signed]' \
':branch:__git_branch_names' \
':upstream:__git_references'
}
_git-check-signed() {
_arguments ':commit range:__git_commit_ranges'
}
# tool hooks
eval "$(ggman shellrc)"

3
zsh/aliases.zsh
View File

@@ -7,6 +7,9 @@ alias n=nvim
alias s="~/.config/bin/ssh-menu"
# notes across ~/git and ~/.config, see claude/rules/notes.md
alias notes='NOTES_ROOTS="$GGROOT:$HOME/.config" python3 ~/.config/claude/skills/notes/notes.py'
# docker
alias dp="docker ps --format 'table {{.Names}}\t{{.Ports}}'"
alias dcp="docker compose ps --format 'table {{.Name}}\t{{.Ports}}'"