Skip to content

GitHub Repository Presentation Playbook

Audience: a Claude Code session setting up (or overhauling) a GitHub repository's public presentation for a lab project — README, documentation structure, community files, and repo settings. This is a procedure to execute, not a narrative to read once.

Reference implementation: LARi-UQAC/ResearchTools, built through this exact sequence. Where a step needs a concrete example, this file points at the real file in that repo rather than inventing one — read the cited file, don't guess its shape.

Scope: this playbook covers presentation and process (how the repo looks, how docs are organized, how contributions flow). It does NOT cover the lab's language/style/security rules for the content of the code or prose itself — those live in .claude/rules/*.md of each project and are out of scope here. If the target repo has its own .claude/rules/, read it first; nothing in this playbook overrides it. One exception is in scope for every repo: the privacy guard (Phase 6b), because a public repo that publishes personal data can only be cleaned by rewriting its history.

Do not fabricate. Every badge, count, and claim below must be verified against the actual repo before being written (file counts, chapter counts, license, existing assets). A number copied from this playbook without checking is exactly the kind of stale claim this whole process exists to prevent.


Phase 0 — Prerequisites

Check before starting, don't assume:

gh auth status          # needs at least: repo, project scopes. Re-check — scopes drift.
gh api user --jq .login # confirms which account is actually authenticated
  • gh CLI installed and authenticated with repo scope (repo settings, badges data) and project scope (Phase 7 board) — see gh auth status. If a scope is missing: gh auth refresh -s <scope>.
  • If the plan includes generating a GIF/image asset: ffmpeg on PATH (ffmpeg -version). On Windows with scoop available: scoop install ffmpeg-essentials.
  • If the plan includes a themed documentation site: Python 3 for a dedicated virtualenv (never reuse a project's own test/runtime venv for doc tooling — see Phase 5).
  • The machine's privacy guard is active, so nothing personal is committed while the repo is being built: git config --global core.hooksPath must print the absolute path of ~/.config/git/hooks (the installer writes the full path, not a tilde), and git config --local core.hooksPath must print NOTHING inside the repo (a local value, such as the one husky sets, silently switches the guard off for that repo), and betterleaks version must answer, and ~/.config/git/hooks must hold the machine-local deny list private-terms.txt (real names; made by install-git-hooks.ps1 -TermsFrom <folder of student projects>, see Phase 6c) and both pre-commit (checks each commit) and pre-push (checks every outgoing commit and its message, so a git commit --no-verify is still stopped before it is published; git push --no-verify skips pre-push as well, and then only CI catches it). If not, install it from a ResearchTools clone: winget install Betterleaks.Betterleaks, then .\.claude\hooks\git\install-git-hooks.ps1. The hooks use a COPY of the rules: re-run the installer after pulling a ResearchTools change to privacy-rules.toml.
  • Ask the user, don't guess, before starting: does this repo already have a CONTRIBUTING.md, design assets, or a documented brand? Overwriting existing work without checking is worse than a slow start.

Phase 1 — Find or define the brand

Do not invent colors. Before picking any palette:

  1. Search the repo for existing design assets — a post-media/, assets/, brand/, or design/-named folder, any .html design template, any style guide doc. This is worth a real search (find . -iname "*brand*" -o -iname "*template*.html" -o -iname "*.dc.html"), not a quick glance — the ResearchTools reference implementation had a full brand system sitting in post-media/Series Template.dc.html (a Claude Design export) that nobody had surfaced into the README before this process ran.
  2. If found: extract the exact hex values (background, primary accent, secondary accent, text color) and the font family. Do not approximate ("looks like teal") — read the CSS values directly.
  3. If genuinely nothing exists: ask the user for 2-3 brand colors, or propose a minimal palette (one dark neutral, one accent) and get explicit sign-off before applying it everywhere. Do not default to a generic palette (a framework's default blue, shields.io's default colors) and call it "the brand."
  4. Record the palette once, in one place (see Phase 5's extra.css for where), and reuse it everywhere — badges, diagrams, the doc site theme. A repo with five different accent colors across its README, its Architecture doc, and its badges looks like nobody is driving.

Phase 2 — Documentation structure

2a. Decide: does the README need to split?

Rule of thumb, not a hard number: past roughly 400-500 lines or when a single README.md covers more than 4-5 genuinely distinct topics (installation, every skill/feature, every command, architecture, file layout...), split it. Below that, a single well-organized README is fine and a split is over-engineering.

If splitting: the reference pattern is docs/manual/, one file per topic, numbered for a stable read order:

docs/manual/
  00-purpose.md          # mission, roadmap, this manual's own conventions
  01-installation.md
  02-<topic>.md
  ...
  NN-file-locations.md   # or whatever the last natural topic is

Chapter file template (every chapter, no exceptions):

# <Chapter Title>

Chapter NN of the <Project> manual. Back to [table of contents](../../README.md).

<content>

---
[← <prev-num> <prev-title>](<prev-file>.md) | [Table of contents](../../README.md) | [<next-num> <next-title> →](<next-file>.md)
  • First chapter: no "← previous" link. Last chapter: no "next →" link.
  • Before moving content out of the root README, grep the project's own test suite for hardcoded reads of that file. A test can assert that specific literal substrings exist in README.md by path (Path(__file__)... / "README.md"), and content moved into a chapter file will fail that test silently — no compile error, just a red test run later. Search Test/*.py, Test/*.ps1, or equivalent, for the literal string "README.md" before restructuring, and either keep the required substrings in the thinned root file (in a pointer/quickstart section) or update the test.
  • If any chapter grows long (over ~300 lines) and has multiple ###-level subsections, add an in-chapter mini table of contents right after the intro, with anchor links to each subsection. Compute the anchors mechanically, do not hand-guess them — GitHub's heading slug algorithm removes em-dashes and slashes entirely (it does not turn them into hyphens), which produces double-hyphens in places a hand guess will get wrong:
import re
def gfm_slug(heading_text):
    s = heading_text.lower()
    s = re.sub(r'[^\w\- ]', '', s)   # strip everything except word chars, spaces, hyphens
    return s.replace(' ', '-')

This is GitHub's own algorithm specifically. If the repo will also be served through MkDocs, Sphinx, or any other renderer, know that their slugifiers are not the same algorithm — an anchor correct on GitHub can silently fail to jump inside a different renderer's build. Verify per target, don't assume portability.

2b. Root README.md becomes the entry point, not the whole story

Once split, the root README.md is a slim landing page: title, badges, a hero visual, a short pitch, a table of contents, and links to every chapter — not the chapter content itself. See Phase 4 for the exact template.

2c. A docs/index.md for an optional documentation site

Add this even before deciding on Phase 5, since it costs nothing: a plain landing page listing every chapter and every deep-dive reference doc, so the docs/ folder itself makes sense to a browsing human even without any site generator running.


Phase 3 — Community health files

GitHub recognizes a specific set of files and reports their presence under Insights → Community Standards. Add each one, adapted to the project (never copy the reference implementation's own contact email, license holder, or project-specific rules verbatim):

File Purpose Notes
CONTRIBUTING.md (root) How to contribute Point to existing detailed docs rather than duplicating install/test steps; keep it thin
CODE_OF_CONDUCT.md (root) Community standard Contributor Covenant v2.1 is a reasonable default; needs a real contact (email or a person), not a placeholder
SECURITY.md (root) Vulnerability reporting State the REAL threat model (a local research tool with no exposed service is not "enterprise compliance scenarios" — don't cargo-cult SOC2/HIPAA language that doesn't apply)
.github/PULL_REQUEST_TEMPLATE.md PR checklist Mirror the project's OWN existing rules (test command, doc-update requirement) rather than a generic checklist — see Phase 7
.github/ISSUE_TEMPLATE/bug_report.md, feature_request.md, config.yml Structured issues config.yml with blank_issues_enabled: false if you want to force template use
.github/CODEOWNERS Default reviewers One line minimum: * @<owner>
.gitattributes Line-ending normalization * text=auto eol=lf plus explicit binary markers for every image/video/document extension in the repo — a binary file with no binary marker risks silent corruption from text normalization
.editorconfig Cross-editor formatting Standard template; exclude .md from trim_trailing_whitespace (Markdown's hard-line-break convention uses a trailing double-space)
.github/FUNDING.yml Native GitHub Sponsor button Only if the project actually has a funding link; check it doesn't already exist before adding
CHANGELOG.md (root) User-facing version history Distinct audience from an engineering decision log if one exists (e.g. this repo's IMPROVEMENTS.md) — a CHANGELOG answers "what changed for someone using this," a decision log answers "why, for whoever maintains it." Don't merge the two.

Check first, every time: .github/FUNDING.yml and similar files may already exist and be correctly configured. Read before writing.


Phase 4 — README.md template

Order that worked, annotated. Adapt content, keep the shape:

# <Project Name>

[![License](...)] [![Language/Platform](...)] [![Docs](...)] [![Stars](...)]
[![Last commit](...)] [![Contributors](...)] [![Open issues](...)]

<!-- Banner: a real rendered image carrying the project's identity + one-line pitch.
     Not the bare logo alone — see Phase 4a on how to actually render one. -->
<p align="center"><img src="path/to/banner.png" alt="..." width="900"></p>

<!-- Logo + a short demo (GIF or screenshot) side by side, in an HTML table for
     GitHub-reliable side-by-side layout (plain adjacent <img> tags wrap unpredictably): -->
<table align="center" border="0" cellspacing="0" cellpadding="0">
<tr>
<td align="center"><img src="logo.png" width="200"></td>
<td align="center"><img src="demo.gif" width="420"></td>
</tr>
</table>

<details>
<summary><b>Table of contents</b></summary>

- [links to every section below]

</details>

<!-- 1-2 sentence pitch, then 3-4 bullets of what it actually does. Bullets should read as
     genuinely distinct capabilities, not a padded, suspiciously symmetric list — vary
     sentence length and structure, or it reads as AI-generated filler. -->

## Why <Project>
<!-- A short before/after table beats a feature list for selling the value proposition.
     Ground every row in a real, named capability — never a generic claim. -->

## See it in action
<!-- A real screenshot or GIF of the actual running tool. Not a mockup. -->

## Quickstart
<!-- The minimum commands to get running. Link to a full install chapter for the rest. -->

## Manual chapters
<!-- If split (Phase 2): a small "at a glance" diagram (Mermaid, in the SAME brand colors
     as everything else — see Phase 1) plus the chapter table. -->

## Supported harnesses / platforms
<!-- If relevant: a row of badges for what's supported, in ONE consistent color rather than
     a different hue per badge — a uniform color reads as "one coherent set," a rainbow
     reads as unplanned. -->

## Support this project
<!-- Sponsor/donate links, star ask — near the BOTTOM, not competing with the pitch at the
     top for the reader's first few seconds of attention. -->

4a. Actually rendering a banner (not just describing one)

A banner built as static HTML/CSS (for precise brand control) needs to be rendered to an image before it's useful in a README — an unrendered .html source file wired nowhere is not a banner, it's a draft. If the session's tools include a headless browser (e.g. a Playwright MCP) but file:// navigation is refused and starting a local server is denied by a permission classifier (both are legitimate safety gates — don't try to bypass either):

  1. Commit the HTML file (and any local image assets it references) to the repo, pushed to GitHub.
  2. Navigate the headless browser to https://htmlpreview.github.io/?https://github.com/<owner>/<repo>/blob/<branch>/<path-to-file>.html — a free public service that serves a GitHub-hosted HTML file back with the correct text/html content type (GitHub's own raw.githubusercontent.com serves it as text/plain, which is why a browser won't render it there) and rewrites the file's relative asset links to resolve against the same repo.
  3. Screenshot the rendered page, save the result as a real PNG asset in the repo, and reference THAT image from the README — not the HTML source.

This only works for a file already pushed to a reachable GitHub location; it does not help preview uncommitted local changes to the HTML.

4b. If the hero is a GIF made from an existing video

Check the first frame before finalizing. A source clip with an intro/background-only lead-in produces a GIF whose resting frame (what a slow-loading page, or any static-preview context, shows) is blank or content-free — this is invisible until checked directly against the live page, not just a local preview. Extract candidate start frames as stills (ffmpeg -ss <t> -i input.mp4 -frames:v 1 probe.png) and look at them before committing to a start offset; don't assume the source "probably starts fine."

Two-pass palette technique for a compact, high-quality GIF:

ffmpeg -ss <offset> -i input.mp4 -vf "fps=12,scale=480:-1:flags=lanczos,palettegen" palette.png
ffmpeg -ss <offset> -i input.mp4 -i palette.png \
  -filter_complex "fps=12,scale=480:-1:flags=lanczos[x];[x][1:v]paletteuse" output.gif

Phase 5 — Optional: a themed documentation site (MkDocs Material)

Only worth it once docs/manual/ (Phase 2) exists with real content — theming an empty folder is wasted effort.

  1. Dedicated environment, never the project's own test/runtime venv:

    python -m venv .venv-docs
    .venv-docs/Scripts/python.exe -m pip install mkdocs-material
    
    Audit it (pip install pip-audit && pip_audit --strict), then remove pip-audit and its own transitive dependencies from the pinned requirements file — they were a one-off audit tool, not a doc-site dependency. Pin what's left with pip freeze.

  2. mkdocs.yml at the repo root, docs_dir: docs, explicit nav: (don't rely on auto-discovery — it will include scratch/plan-authoring content you don't want on a public site), and the brand palette from Phase 1 applied via extra_css overriding Material's CSS variables (--md-primary-fg-color, --md-accent-fg-color, etc.) rather than settling for Material's nearest built-in named color.

  3. exclude_docs: for anything under docs/ that isn't meant for the site (a plan-authoring scratch folder, work-in-progress notes). not_in_nav: is NOT an exclusion — it only hides a file from the sidebar while still building it, and a malformed file that GitHub's renderer tolerates can still crash MkDocs's own build (a Python-Markdown/HTML-parser edge case is a measured example). Use exclude_docs: for anything that must not be processed at all.

  4. Build locally and read the warnings, don't just trust the source: mkdocs build (add --strict to fail on any warning, useful for a first pass, but expect and accept two categories of warning as informational rather than bugs — see the gotchas below).

  5. No CI/CD if the project has a "no automated pipeline" policy (the privacy-scan workflow of Phase 6b is the one exception in every repo, and the billed review workflow of Phase 6d is a second one only where the user opted in): publish with a manual mkdocs gh-deploy (pushes a gh-pages branch by hand) rather than a GitHub Actions workflow. Document the manual command in docs/index.md. Enabling the Pages setting itself (Settings → Pages → Deploy from branch → gh-pages) is a repo-settings change for the human to make, not something to script.

Known, acceptable gaps to document rather than "fix" into a bigger scope: - A link from inside docs/ to a file OUTSIDE docs_dir (e.g. the root README.md, Architecture.md) resolves fine on GitHub's own browser but not inside the MkDocs build, since its docs_dir only knows about docs/. State this, don't silently break the GitHub-browsing experience trying to force both to work identically. - GitHub's own heading-slug algorithm and MkDocs/Python-Markdown's slugifier diverge (see Phase 2a) — an in-page anchor correct on GitHub can fail inside the built site.


Phase 6 — GitHub repository settings (via gh, verify before and after)

All of these are real API calls with real effects — read the current state first, and read it back after to confirm, rather than trusting a silent success:

# Current state, before touching anything
gh api repos/<owner>/<repo> --jq '{description, has_wiki, has_projects, has_discussions, topics}'

# Description + topics ("About" section — the first thing a visitor sees, before README)
gh repo edit <owner>/<repo> --description "<one sentence>" \
  --add-topic <topic1> --add-topic <topic2> ...

# Discussions on, if useful for informal Q&A separate from Issues
gh api -X PATCH repos/<owner>/<repo> -f has_discussions=true

# Wiki off, IF genuinely redundant with docs/manual/ + a doc site — ask first, don't assume
gh api -X PATCH repos/<owner>/<repo> -f has_wiki=false

# Verify
gh api repos/<owner>/<repo> --jq '{description, has_wiki, has_projects, has_discussions, topics}'

Secret scanning + push protection. Free on a public repo (part of GitHub Advanced Security, which is paid on private); check visibility first — gh repo view <owner>/<repo> --json visibility,isPrivate. Different from a local pre-commit hook or this repo's own betterleaks-hook.py: those run client-side, before or after a write, and are trivially skipped (--no-verify, or simply not installed); this runs server-side on GitHub, on every push, unconditionally. Enable both together — scanning alone only flags a leaked secret after it has already landed in history; push protection refuses the push itself:

gh api -X PATCH repos/<owner>/<repo> \
  --input - <<'EOF'
{
  "security_and_analysis": {
    "secret_scanning": {"status": "enabled"},
    "secret_scanning_push_protection": {"status": "enabled"}
  }
}
EOF

# Verify
gh api repos/<owner>/<repo> --jq .security_and_analysis

The same --input - JSON-body pattern is the correct way to PATCH any nested security_and_analysis field — gh api -f key.nested=value does not build nested JSON, only flat top-level fields; a dotted -f key is sent as a literal flat key, not a nested object, and GitHub silently ignores it rather than erroring, so the flag being accepted proves nothing.

6b. Privacy guard (every repo, before it is public)

Push protection only knows secret formats (API keys, tokens). Personal data under Quebec's Law 25 (an account name in a path, a student's code permanent, an @etu.uqac.ca address, an FRQ identifier) needs the lab's own rules, .claude/hooks/git/privacy-rules.toml in LARi-UQAC/ResearchTools. Measured 2026-10-01: ResearchTools published such values in files AND history, and cleaning it took a git filter-repo rewrite, a force-push past the ruleset, a GitHub Support request and fork owners deleting their forks. Do the four steps below.

  1. Scan the full history before the repo becomes public (or right after creating it). Zero findings is the only acceptable result; any finding is removed BEFORE the visibility changes, since afterwards only a history rewrite removes it:
rules=$(realpath <path-to-ResearchTools>/.claude/hooks/git/privacy-rules.toml)
git log -p --all --text -m --pretty=medium --no-color --no-ext-diff --no-textconv \
  | (cd "$(mktemp -d)" && betterleaks stdin --redact --no-banner --config "$rules")

betterleaks runs from an empty directory because an ignore file (.gitleaksignore, .betterleaksignore) in its current directory hides findings; the repository's own copy is left untouched. The rules path is absolute for the same reason.

Not betterleaks git: measured 2026-10-02 with betterleaks 1.4.1, it honours a .gitattributes -diff (the file reads as "Binary files differ") and skips what a merge commit adds. The text pipe above sees both. It also reads each commit's Author and Date lines, so a commit authored with an @etu.uqac.ca address is reported; that is wanted before publishing (CI scans content and messages only).

The pipe still cannot read UTF-16 text or the content and metadata of binary files (author fields included). Check those separately, each through the same scanner (scan below stands for (cd "$(mktemp -d)" && betterleaks stdin --redact --no-banner --config "$rules"); the first three were verified 2026-10-09 on fixtures carrying a code-permanent shape):

  • UTF-16 text: list it with git ls-files -z | xargs -0 file | grep -i utf-16, then iconv -f UTF-16 -t UTF-8 <file> | scan;
  • .docx / .xlsx / .pptx: unzip -p <file> 'docProps/*' 'word/*' 'xl/*' 'ppt/*' | scan (docProps/core.xml holds the author and last-modified-by fields);
  • .pdf: { pdfinfo <file>; pdftotext <file> -; } | scan (Poppler, shipped with MiKTeX);
  • images: no scanner was available on the reference machine, so check the EXIF author and GPS fields in the file's properties, or strip metadata before committing.

  • Add the CI check as .github/workflows/privacy-scan.yml. It reuses the ResearchTools workflow and its rules, so every repo follows one rules file:

name: privacy-scan
on:
  pull_request:
    # edited: a PR retargeted to another base is scanned again against that base
    types: [opened, synchronize, reopened, edited]
  push:            # every branch, not only main: a branch with no PR is public too
permissions:
  contents: read
jobs:
  privacy-scan:
    uses: LARi-UQAC/ResearchTools/.github/workflows/privacy-scan.yml@main
  1. Make it a required check once it has run once. Read the exact check name from that run (gh pr checks <pr>; a caller usually shows privacy-scan / privacy-scan), then add it to the branch ruleset with a read-modify-write that keeps every existing rule and bypass actor, and read the ruleset back (the reference is the ResearchTools "Main protection" ruleset):
gh api repos/<owner>/<repo>/rulesets --jq '.[] | {id, name}'      # find the ruleset id
gh api repos/<owner>/<repo>/rulesets/<id> > ruleset.json
# add {"type":"required_status_checks","parameters":{"strict_required_status_checks_policy":false,
#      "do_not_enforce_on_create":false,"required_status_checks":[{"context":"<check name>",
#      "integration_id":15368}]}}
# integration_id 15368 is the GitHub Actions app (read from a real check run's app.id):
# without it, a commit status any collaborator posts by API satisfies the check.
# to .rules, keep name/target/enforcement/conditions/bypass_actors, then:
gh api -X PUT repos/<owner>/<repo>/rulesets/<id> --input ruleset-new.json
gh api repos/<owner>/<repo>/rulesets/<id> --jq '[.rules[].type]'  # verify

No ruleset yet: create one on refs/heads/main with deletion, non_fast_forward, pull_request and this required_status_checks rule, admin bypass only. The pull_request rule must require code-owner review, with a .github/CODEOWNERS covering .github/workflows/ (* @<owner> is enough): the caller workflow lives in the repo itself, so without that review a PR could repoint uses: at a fork with empty rules, or pin an old version, and still report a green privacy-scan.

The push runs only DETECT: a pushed branch is already public, and [skip ci] or an edited workflow in that push suppresses the run. The merge into main is what the required check protects; the machine hooks (Phase 0, pre-commit and pre-push) are what stop a value before it is published. The triggers above live in the caller: a workflow_call ignores the on: of the called workflow, so a caller without edited is not rescanned after a retarget.

  1. Test data uses fictitious identities only (ResearchTools rule R34): Wick, J., student@example.org, XXXX000000, XXXYY1234. No pattern can recognise a real name, so a real student or co-author in a fixture passes every check. A deliberate sample that must look real (a test of the guard itself) carries betterleaks:allow on its line.

Gotcha: the CI scans EVERY commit a pull request adds, so a bad first commit stays flagged even after a fix commit on top. Resubmit the change as one clean commit on a new branch (git merge --squash onto a fresh branch from main) and close the old PR - measured on ResearchTools PR #39, replaced by #40.

6c. When personal data was published anyway (and how to stop the next one)

Measured 2026-10-12 on ResearchTools PR #69: a real student's name was committed inside a Windows data-folder path (<drive>:\...\<StudentName>\...) copied verbatim from a real run into a test fixture. The pre-commit hook, the pre-push hook and the CI scan all answered "no leaks found". It had happened before with a code permanent (2026-10-01).

Why every layer passed. The rules in privacy-rules.toml match SHAPES: a home path under \Users\, /home/, a permanent code, @etu.uqac.ca, an FRQ id. A name is not a shape, and a path on a data drive (D:\<folder>\...) is not a home path. Nothing in the chain holds the list of real names the operator works with, and that list cannot live in a public rules file, because publishing it is the leak. The cause upstream of the guard is the habit: real output (a path, a log line, a file name) pasted into a test, a doc or a commit message.

Improve the process, in this order of value:

  1. Never let real data reach the repository's inputs. Run a tool under development against a COPY of the real student file renamed to a fictitious identity, or against a synthetic fixture. Output pasted into a test, a doc, an IMPROVEMENTS.md line or a commit message is written from the fictitious run, never copied from the real one. R34 states the rule, this step makes it a working procedure.
  2. Use the machine-local deny list, read by the hooks, never committed. Implemented 2026-10-12 in .claude/hooks/git/ (privacy-lib.sh, privacy-extra.awk). Generate it from the folders that name real people, then reinstall the hooks:
.\.claude\hooks\git\install-git-hooks.ps1 -TermsFrom "<folder of student projects>" -TermsDepth 2

The person-folder names found -TermsDepth levels down are split at capitals and written to ~/.config/git/hooks/private-terms.txt. Run the command for every new student: the file is only ever appended to, never rewritten, and only counts are printed. Terms typed by hand (the name of a data root folder, a co-author, a lab-internal project name) go in private-terms.extra.txt beside it, which the installer never touches. Both hooks refuse a term, case-insensitively, in an added line, an added or modified path, a commit message or a commit author line, and name the file, not the line or the term. A name inside data_name_run or DataName is found, nameville is not. Deleting a leaked path is never refused, it is the cleanup. Rerun the installer whenever a new student folder appears: it appends the missing names to the file, so earlier names, a graduated student's folder that left the disk and lines typed by hand all stay. It sets aside ordinary words (deny-term-stopwords.txt) in private-terms.excluded.txt, where a real surname that equals one is found and moved to the extra file, refuses a folder that yields nothing, and warns when no list exists yet. The list holds real names, so the installer refuses to write it into a synchronized or shared folder (OneDrive, Dropbox, Google Drive, iCloud, Nextcloud, a network share, a junction into one of them) and says which category it found, never the path. If your home folder is synchronized, run -Uninstall and install again with -Target <local folder>. It also adds private-terms.txt, private-terms.extra.txt and private-terms.excluded.txt to the global git ignore, so a copy dropped into a repository cannot be staged by accident. 3. Check absolute paths in fixtures. An absolute drive path added to a file under Test/, tests/, fixtures/ or named test_* is reported unless it matches the fictitious roots of fixture-path-allow.txt (C:\Work, C:\Example, ...). Default is a warning on stderr, because existing fixtures legitimately carry paths; once the tree is clean, git config --global privacyguard.absolutePaths refuse makes it a refusal, and off disables it. A deliberate line carries betterleaks:allow. 4. No copy of the deny list in CI (rejected). A repository secret read by the privacy-scan workflow would give the server-side check the same terms, but the list holds real names and a secret is still data leaving the machine. The owner ruled it out on 2026-10-15, so the CI scan stays shape rules only (privacy-rules.toml), and names stay covered by the local hooks (step 2), R34 and the human read of step 5. The consequence is stated, not hidden: GitHub comments, pull-request bodies and issue text, the leak path of the PR #69 incident, have no automatic control at all. Never paste a name or a real path there. 5. Make the last look human. Before any push of a branch that touched fixtures, docs or commit messages, list the added lines that contain an absolute path or a capitalised two-word name and read them: git diff origin/main...HEAD -U0 | grep -E '^\+' | grep -E '[A-Za-z]:\\|[A-Z][a-z]+ [A-Z][a-z]+'. Noisy by design. It is the only layer that can see a name nobody listed. 6. Do not push first and check later. The scan runs on the local branch before the first push of a new branch. A pushed branch is public the moment it lands, and the only cleanup is a history rewrite plus a purge request.

Cleanup when it already happened.

  • Rewrite the branch (git filter-branch or git filter-repo), verify with a full-history scan, force-push with --force-with-lease=<branch>:<old-sha>. This removes the branch content but NOT the old commits: GitHub keeps them reachable by SHA, through the pull request's cached views, and in every fork.
  • Ask GitHub Support to remove the cached views and run garbage collection, with the exact SHAs and the pull-request number. GitHub may refuse when the data is not a credential: a code permanent or a name is personal data, not a secret, and the support policy centres on secrets. Nothing in this playbook can force a purge.
  • If support refuses, the options that remain are: delete and recreate the repository (the only certain removal, at the cost of issues, pull requests, stars, the Pages site and the fork network, then re-import the clean history); or accept the exposure of the old SHAs until GitHub garbage-collects the unreferenced objects, which has no guaranteed date. Decide with the privacy officer, not alone.
  • Treat it as a confidentiality incident under Law 25: tell UQAC's privacy officer promptly, record the incident, and let that office assess the risk of serious injury and any notice to the person concerned. Confirm the exact obligations with UQAC; this playbook does not replace that advice.

Social preview image and enabling the Pages setting itself are web-UI-only — no API path for either as of this writing. Prepare the asset (Phase 4a's banner is a better fit than a bare logo for the image, given GitHub's ~1280×640 social-card aspect ratio), then hand the human the exact setting path (Settings → Social preview / Settings → Pages).

First version tag, once content is in a shippable state — don't invent a version number unilaterally, it's a public-facing decision:

git tag -a v0.1.0 -m "<summary>"     # ask the user for the actual number, don't assume 0.1.0 fits
git push origin v0.1.0               # a push — confirm the project's own git-ownership norms first (Phase 8 note)
gh release create v0.1.0 --title "..." --notes "..."

6d. Optional: automated multi-dimension PR review (billed)

Adds a second workflow beside privacy-scan: on every pull request a headless Claude Code session runs the two review skills built into Claude Code (security-review, code-review), deliberates across their findings itself, and a LATER step that holds no key posts ONE Critical/High/Medium/Low list as a PR comment (updated in place) and a copy on the linked Issue, with the PR author mentioned once and assigned. Reference: .github/workflows/review.yml, scripts/ci/review_mirror.py and the "CI" section of .claude/rules/testing.md in LARi-UQAC/ResearchTools (Issue #65, PR #67). Read the real files and copy their structure; the decisions below are why they look that way.

Ask first, because of cost and trust. Unlike privacy-scan (static, free) this spends real Anthropic API tokens on every PR run and gives a model a secret. Get an explicit yes, and state both. Without the yes, stop here.

Prerequisites, each verified, none assumed:

  • Repo secret ANTHROPIC_API_KEY (gh secret list is empty on a fresh repo). Only the human adds it (Settings → Secrets and variables → Actions). Never ask for the key in the session and never write it to a file. Until it exists the first step of the job says so and every other step is skipped, so the check ends neutral rather than red, which is the correct inert state.
  • The first run uses a throwaway key. A dedicated Anthropic key with a low spend limit, added by the human, used for one run on a throwaway PR, then rotated. The offline suite cannot show what the real action does, so that run is where you read the log for: the session's tool list (the check-tools step passed), the /proc deny rules refusing a read, both skills actually running, and the PR comment created. Never put the production key in a workflow that has not had this run.
  • Load NO plugin in the step that holds the key. In headless mode the action installs plugins ONLY from its own plugins: and plugin_marketplaces: inputs (read base-action/src/install-plugins.ts in anthropics/claude-code-action), the checked-out .claude/settings.json enabledPlugins is ignored, and the marketplace URL must end in a bare .git (the regex rejects a ref or SHA), so a marketplace always loads from its moving default branch and cannot be pinned. Third-party code that can change unreviewed must not run beside the API key. So use only the skills built into Claude Code (security-review, code-review, bare names). A plugin skill such as ai-firstify:ai-firstify or engineering:tech-debt resolves only under its qualified name, so if you ever add one, read the name off the skill listing, but first decide how to pin it: copying it into the repo is barred in ResearchTools (R36 part 4), authoring your own reviewed skill is the allowed path.

Workflow structure that survived four review rounds (the order matters):

  1. Trigger: pull_request types opened, synchronize, reopened. Not pull_request_target (it would hand the secret to fork PRs; plain pull_request withholds it from forks), and a job-level if: github.event.pull_request.head.repo.full_name == github.repository skips fork PRs and github.actor != 'dependabot[bot]' skips Dependabot (neither gets the secret), so their checks do not go red. No workflow_dispatch: the diff step needs the pull-request event context and a manual run would fail before the review starts. concurrency per PR number with cancel-in-progress, so a new push replaces a run you would otherwise pay for twice. Workflow-level permissions is the floor contents: read only. Each job then sets its own (steps 3 and 4), so no job holds the key, the agent and issues: write together.
  2. First step: read the secret into an env: variable and set a step output present. When it is empty print a ::notice naming the secret and skip every later step with if: steps.key.outputs.present == 'true', so the check ends neutral. Then checkout with fetch-depth: 0 AND persist-credentials: false (the default leaves the job token in git config, readable by the model's Read tool; the diff step needs no network after a full fetch). A plain step writes the diff to $RUNNER_TEMP/pr.diff (git diff "origin/$BASE_REF"...HEAD, three dots = against the merge base), with pathspec exclusions for the files your installer regenerates from canonical sources, cut at a MAX_DIFF_BYTES env value on a line boundary so a mirror or lockfile cannot run up the bill. Take that number from the user or mark it unmeasured. Claude reads that file.
  3. The Claude step runs in agent mode only: do NOT set track_progress or use_sticky_comment. Measured from the action source (src/modes/detector.ts, src/modes/tag/index.ts), track_progress forces the action's tag mode, which builds the session's tool list with Bash(git add|commit|rm), a push wrapper, acceptEdits and CI-log tools before appending yours, so "no Bash" is false the moment it is set. Pin the session with claude_args: --tools "Skill,Read,Grep,Glob" plus the same list in --allowedTools: no Bash, no Agent/Task, no MCP tool. The diff is untrusted content and the secret sits in this step's process: a crafted line in the diff could make the model run gh ... --body "$ANTHROPIC_API_KEY" (child shells inherit the environment, and an allowed-tool wildcard limits the command prefix, not variable expansion inside it). Withholding Agent/Task keeps a sub-agent spawned by a skill from carrying tool access nobody audited, so the prompt tells Claude to run each skill inline. State this thoroughness tradeoff in a comment. Pass github_token: ${{ github.token }} explicitly: without it the action tries an OIDC exchange for a GitHub App token, which needs id-token: write. Deny Read, Grep AND Glob of /proc, /sys and /run (--disallowedTools, nine rules), because Read of /proc/self/environ would hand the key to a prompt-injected read; the path syntax of that deny rule is unverified until the first real run, so say so. Make the prompt require a fixed first line and a second line naming which skills ran, so a skill that silently did not run is visible.
  4. Key-less steps after the agent, in the same job (it has pull-requests: write and no issues: write): a guard reads the tool list of the session's own init message from the action's execution_file output and FAILS the job when ANY tool outside the four allowed ones is present or the list cannot be read (an allowlist, so a tool nobody thought to forbid is refused too; detection after the fact, prevention being step 3), then an extract step pulls the model's final reply out of the same file and refuses an error result or a reply that does not start with the fixed marker line, then a post step sanitises the reply (no mention, no #N or owner/repo#N reference, no link, no remote image, no raw HTML, no bare URL) and creates or updates ONE PR comment carrying a hidden marker line and the reviewed commit. In ResearchTools these are the check-tools, extract and post-pr subcommands of scripts/ci/review_mirror.py. Putting the logic in a tested script rather than shell inside YAML is what lets an offline suite assert it.
  5. A separate mirror JOB (needs: review, if: needs.review.outputs.reviewed == 'true'), not just a separate step: the review job has contents: read + pull-requests: write and the mirror job contents: read + pull-requests: read + issues: write, with a workflow-level floor of contents: read only. A job-level permissions: replaces the workflow's, so the agent's token cannot write Issues and the job that can has no key. It checks out only the script (sparse-checkout, persist-credentials: false), reads the PR comment back BY ID (a job output) and rejects it unless its author is github-actions[bot] and the hidden marker is present, then creates or updates ONE Issue comment, mentioning the author only when it creates it. A missing or foreign PR comment fails the job: a silent exit 0 is how a review quietly stops being mirrored. Take the Issue number only from a line that STARTS with Fixes #N or Closes #N and check it is an open Issue and not a pull request (gh api repos/<o>/<r>/issues/<N> has a pull_request key for a PR); an assignee failure (a non-collaborator author) must not turn the job red. Route every PR-controlled value (PR_BODY, PR_AUTHOR, BASE_REF) through env:; a ${{ }} expression inside a run: block is pasted into the script before bash parses it, which is script injection. A diff cut at MAX_DIFF_BYTES must make the reply say the review is partial.
  6. Pin every uses: to a commit SHA. For an annotated tag, git/refs/tags/<tag> returns the tag object, which is not a commit and will not resolve in uses:. Check: gh api repos/<o>/<r>/commits/<tag> --jq .sha (the commit) against gh api repos/<o>/<r>/git/refs/tags/<tag> --jq .object.type (commit is safe, tag is not).

Do not make it a required check yet. Its output is advisory, it costs money on every run, and a required check that ends neutral without the secret would let a merge pass unreviewed without anyone noticing. Decide with the user after a few real runs.

Docs this change makes false, in the same PR (a code review found each one): the "only CI is privacy-scan" sentences in CONTRIBUTING.md, .claude/rules/testing.md (top paragraph and its CI section) and .claude/rules/workflows.md, then regenerate the mirrors (.\install.ps1 -Profile <active>) so .github/instructions/*.instructions.md agree. Grep for only CI, One workflow only and only automated check to find them all.

Test it for real. YAML that parses proves nothing about behavior. After the human adds the secret (the throwaway key of the prerequisites), open a throwaway PR and read: the check-tools step passed and the session's tool list in the log holds only Skill, Read, Grep and Glob, the /proc deny rules refused a read, the PR comment exists and a second push updated it instead of adding another, both skills actually ran (none silently missing), the Issue got ONE comment, the assignee call succeeded or degraded with its message, and the key appears nowhere in the run log. Then rotate the key. Record the observed values in the PR, since the workflow's header lists them as UNVERIFIED until this run.


Phase 7 — Process rules: Issue/board/PR/docs discipline

If the target project has its own numbered-rule convention (like .claude/rules/*.md R-numbers in this codebase), ADD to that sequence — check the current highest number first (grep -rhoE "\*\*R[0-9]+" .claude/rules/*.md | sort -t R -k2 -n -u | tail -5) and update any index/cross-reference that states the old bound in the SAME edit (see the gotcha below). If the project has no such convention, write these as plain prose policy in CONTRIBUTING.md instead of inventing a numbering scheme it doesn't otherwise use.

Pattern 1 — a PR needs a linked Issue and a board card before it opens. Reference implementation: .claude/rules/workflows.md R30 in LARi-UQAC/ResearchTools. Steps: open an Issue naming the problem → add it to the repo's own GitHub Project board (gh project item-add <project-number> --owner <owner> --url <issue-url>) → open the PR referencing the Issue (Closes #<N>). Exempt trivial fixes (typo, broken link) from the ceremony.

Pattern 2 — a PR does not merge until the documentation it touches is updated, in the same PR. Reference implementation: R31 in the same file. This is a merge-time gate the reviewer checks, complementing Pattern 1's open-time gate — "will fix docs later" is not an approval.

Setting up the board, if one doesn't exist for the repo yet:

gh project create --owner <owner> --title "<Project> Roadmap"
gh project link <number> --owner <owner> --repo <owner>/<repo>
# Seed it with existing open issues:
gh project item-add <number> --owner <owner> --url <issue-url>
# And with draft cards for anything already written as a prose roadmap somewhere in the docs:
gh project item-create <number> --owner <owner> --title "<item>" --body "<context>"

Gotcha, measured on this exact playbook's own reference implementation: a rule file that lists a numeric range or count another file also states (e.g. "rules R0 to R27", "18 skills") WILL drift the next time a new item is added, unless updating every place that states the old bound is treated as part of the same edit — not a follow-up. This repo's own .claude/rules/code-style.md "Rule identifiers" index had silently stopped naming two rules for an unknown number of sessions before this playbook's authoring cycle caught and fixed it. Grep for the old bound and fix every hit, every time.

Gotcha — junction/symlink propagation: if the rules directory being edited is shared across multiple projects via a symlink or directory junction (check the project's own install docs), an edit here goes live EVERYWHERE that junction reaches, immediately, with no sync step and no guard rail. A rule drafted with a concrete example from the current repo (a literal project-board URL, a literal owner name) will read wrong the moment another project's session reads it. Phrase the generalizable rule generically ("the repo's own board") and cite the concrete example separately, clearly marked as one instance rather than the universal target.


Phase 8 — Verification checklist (run before handing back)

  • [ ] Every internal markdown link resolves — script it, don't eyeball a 100+-line README:
    import re, os
    # walk every changed .md file, regex for ']( ... )', skip http(s) and '#'-only anchors,
    # os.path.normpath+exists() the rest relative to the file's own directory
    
  • [ ] If the project has an offline test suite that reads README.md or another doc file by literal path for required substrings (see Phase 2a), re-run it after every doc edit — not just once at the end.
  • [ ] After pushing: compare the local committed blob SHA against what GitHub actually serves (git rev-parse HEAD:<path> vs gh api repos/<owner>/<repo>/contents/<path> --jq .sha) for anything that "should just work" but is easy to get wrong (binary assets especially). A byte-for-byte cached CDN response can look like a bug that isn't one — check this before assuming a push failed.
  • [ ] Actually LOOK at the live rendered page (a headless-browser screenshot of the real https://github.com/<owner>/<repo> URL) at least once — a markdown source that "should" render correctly can still surprise you (an animated GIF's static first frame, a badge that silently fails to fetch its logo, a collapsed <details> block that looks broken collapsed). Don't declare success from source inspection alone.
  • [ ] Clean up debug artifacts before finishing: screenshots taken for verification, headless browser snapshot files (check for a stray directory left behind, e.g. .playwright-mcp/), temp probe frames. Add a .gitignore entry for the tool's own debug output directory if this is a recurring pattern, so it can't be accidentally committed again — this repo found one such file that had been sitting committed since an earlier, unrelated session.
  • [ ] Privacy guard (Phase 6b), each item READ BACK, not assumed:
  • full-history scan (the text pipe of Phase 6b step 1) with the lab rules: zero findings, and every UTF-16, .docx, .pdf and image file checked with the per-type commands of that same step;
  • git config --local core.hooksPath prints nothing in the repo (Phase 0);
  • the caller workflow lists edited under pull_request: types;
  • .github/CODEOWNERS covers .github/workflows/, and the ruleset's pull_request rule has require_code_owner_review: true;
  • security_and_analysis shows secret scanning AND push protection enabled;
  • the privacy-scan check is green on a real pull request;
  • the branch ruleset lists that check under required_status_checks;
  • the added lines of the branch were read by a human for absolute paths and names (Phase 6c, step 5), because no rule recognises a name.
  • [ ] Review workflow (Phase 6d), only if the user opted in, each item READ BACK:
  • ANTHROPIC_API_KEY exists (gh secret list), added by the human, a throwaway key for the first run and rotated after it;
  • every uses: is pinned to a commit SHA (annotated-tag check of 6d step 6);
  • the Claude step sets --tools to Skill,Read,Grep,Glob, no Bash, no Agent, and neither track_progress nor use_sticky_comment;
  • every checkout has persist-credentials: false;
  • no ${{ }} expression inside any run: block for PR-controlled fields;
  • with the secret absent the check ends neutral, not red;
  • a throwaway PR produced the PR comment (updated in place by a second push), ONE Issue comment and the assignment, and the log shows no secret;
  • no document still claims privacy-scan is the only CI (grep of 6d).
  • [ ] Respect the project's own git-ownership norm. Some projects want the session to commit and push freely; others want every commit/push left to the human. This is NOT universal and can change mid-session — if told "let me commit and push myself," that applies from that point forward, including for work already staged. Don't assume a general "yes, go ahead" from earlier in a session extends to git operations unless it was said about git specifically.

Appendix — Things this playbook got wrong the first time (keep this section growing)

Real, measured mistakes from building the reference implementation, so the next run doesn't repeat them:

  • Assumed a video file's opening frame was representative without checking — it was a content-free background blur, invisible until verified against the actual live page.
  • Assumed file:// rendering was categorically blocked with no alternative, and told the user so — a working https:// route (htmlpreview.github.io) existed and was found only after being asked to try again.
  • Hardcoded a specific repo's project-board URL directly into a rule meant to generalize across every project a shared rule file reaches.
  • Left a stale "R0 to R27" bound in a cross-reference index for at least two rule additions before it was caught.
  • Assumed a differently-named file (LogoLARI_FINAL.png vs LogoLARI_trim.png) sitting at the repo root was dead duplicate weight without checking — it was referenced by a separate pipeline. Grep before proposing a deletion, every time.
  • Treated secret scanning + push protection as the whole of "security" for a public repo. On 2026-10-01 ResearchTools was found publishing an account name, a machine path, code-permanent-shaped values, student emails and a real name in files and history - none of which push protection recognises. Phase 6b exists because of it.
  • First review workflow draft (2026-10-09) gave the model Bash(gh ...) to post its own comments, which put the API key one prompt injection away from a public comment. It also inlined github.event.pull_request.body into a run: block, pinned claude-code-action to an annotated tag object instead of its commit, named the ai-firstify skill without its plugin qualifier, relied on .claude/settings.json to install plugins in CI, and left a workflow_dispatch that could not work. Each was caught by a local review before any PR, which is why Phase 6d prescribes that review.
  • Shipped the review workflow loading two third-party plugins from their default branches in the step that holds the API key, and documented the missing pin as a "known gap". An automated review called it a supply-chain risk and it was one: the action cannot pin a marketplace, so the fix was to remove the plugins from CI, not to describe the gap. Copying them into the repo was not an option either (R36 part 4).
  • Wrote "no Bash, no Write/Edit" into the workflow, the tests doc and the playbook as an established fact while track_progress: "true" was set. Read from the action's own source (2026-10-16, PR #67 review), that input forces the tag mode, which hands the session Bash(git ...) and edit rights before the workflow's --allowedTools is even appended. The claim had never been checked against the action, and the failed run's log already showed the default tool list. Check what an action adds to a session by reading its source or a real log, never from the inputs you passed. The same review found the checkout leaving the job token in git config (persist-credentials defaults to true) and a mirror whose logic could only be tested by running it.
  • Updated testing.md for the new workflow and called it done; the same stale "only CI is privacy-scan" claim sat in three other files and in the Copilot mirrors until a code review found them. Grep for the old claim, then regenerate the mirrors.
  • Trusted a green privacy guard as proof that no personal data was published. On 2026-10-12 a student's real name, inside an absolute data-folder path pasted from a real run into a test fixture, passed pre-commit, pre-push and CI: the rules match shapes, and a name is not a shape. GitHub then declined to purge the old commits. Phase 6c exists because of it. A green scan means "no known shape", never "nothing personal".