From a023a4a5961882366d6b9473c1f7effe41fdb2b9 Mon Sep 17 00:00:00 2001 From: Julian Montez Date: Sun, 4 Oct 2026 09:22:18 -0400 Subject: [PATCH 1/3] Clone and link the private knowledge repo bootstrap clones jpmontez/knowledge to ~/Development/knowledge when gh has access and runs its link.sh, which symlinks each OKF bundle into place and hides the links via .git/info/exclude. doctor runs link.sh --check. Forks without access skip both. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 5 +++++ README.md | 17 ++++++++++++++++- bootstrap.sh | 16 ++++++++++++++++ doctor.sh | 12 ++++++++++++ lib.sh | 7 +++++++ 5 files changed, 56 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 1535aea..b12471f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,6 +10,11 @@ Personal dotfiles managed with GNU stow. Full details: README.md. - `bootstrap.sh` installs + stows everything (idempotent, safe to re-run). `doctor.sh` is read-only drift detection only — never edits anything. +- `KNOWLEDGE_REPO`/`KNOWLEDGE_DIR` in `lib.sh` point at the private OKF + knowledge repo; bootstrap clones it and runs its `link.sh`, doctor runs + `link.sh --check`. Never commit a `knowledge/` directory here: it is a + symlink hidden through `.git/info/exclude`. + ## Conventions - New dotfile: create/extend a package dir mirroring `$HOME`, then add the package name to `STOW_PACKAGES` in `lib.sh`. Don't hand-symlink or diff --git a/README.md b/README.md index 16a7633..a59bac5 100644 --- a/README.md +++ b/README.md @@ -119,6 +119,21 @@ repo. `doctor.sh` flags it if it ever folds back. --- +## Private knowledge bundles + +Claude Code's [Open Knowledge Format](https://github.com/GoogleCloudPlatform/open-knowledge-format) +bundles live in a separate private repo, `jpmontez/knowledge`, cloned to +`~/Development/knowledge`. Its `link.sh` symlinks each bundle to where sessions +look for it (`/knowledge`, `~/.claude/knowledge`) and hides the links +through each repo's `.git/info/exclude`, so nothing from it lands in this or any +other public repo. + +Bootstrap clones it when `gh` is signed in with access and runs `link.sh`; +otherwise it skips the step. `doctor.sh` runs `link.sh --check`. It's optional, +so a fork without access loses nothing. + +--- + ## Submodules | Submodule | Repo | @@ -133,7 +148,7 @@ repo. `doctor.sh` flags it if it ever folds back. ## Post-Install 1. **SSH keys** — copy or generate into `~/.ssh/` (`ssh-keygen -t ed25519`). It's a real directory, so keys stay out of the working tree. -2. **GitHub CLI** — `gh auth login`. +2. **GitHub CLI** — `gh auth login`, then re-run `./bootstrap.sh` to clone and link the private knowledge repo. 3. **App Store** — sign in, then re-run `brew bundle` if `mas` entries were skipped. 4. **tmux plugins** — TPM auto-installs on first launch; `prefix + I` after adding plugins later. 5. **Check your work** — `./doctor.sh` should come back clean. diff --git a/bootstrap.sh b/bootstrap.sh index f9fcb63..6589528 100755 --- a/bootstrap.sh +++ b/bootstrap.sh @@ -199,6 +199,22 @@ if [[ "$SHELL" != "$ZSH_PATH" ]]; then chsh -s "$ZSH_PATH" || echo ">>> Warning: could not change default shell automatically; run 'chsh -s $ZSH_PATH' manually." fi +# ---- Private knowledge bundles ---- +# Optional: needs a GitHub login that can see the repo, so a first run on a new +# machine (before `gh auth login`) or a fork just skips it. +if [[ ! -d "$KNOWLEDGE_DIR" ]]; then + if gh auth status &>/dev/null && gh repo view "$KNOWLEDGE_REPO" &>/dev/null; then + echo ">>> Cloning $KNOWLEDGE_REPO..." + gh repo clone "$KNOWLEDGE_REPO" "$KNOWLEDGE_DIR" + else + echo ">>> Skipping $KNOWLEDGE_REPO (not signed in to gh, or no access). Re-run after gh auth login." + fi +fi +if [[ -x "$KNOWLEDGE_DIR/link.sh" ]]; then + echo ">>> Linking knowledge bundles..." + "$KNOWLEDGE_DIR/link.sh" || echo ">>> Warning: some knowledge links need attention (see above)." +fi + # ---- macOS system defaults ---- applied_defaults=0 if [[ "$PLATFORM" == "macos" ]] && (( APPLY_DEFAULTS )); then diff --git a/doctor.sh b/doctor.sh index b9095dc..1be0a41 100755 --- a/doctor.sh +++ b/doctor.sh @@ -142,6 +142,18 @@ else ok "working tree clean" fi +if [[ -x "$KNOWLEDGE_DIR/link.sh" ]]; then + if links="$("$KNOWLEDGE_DIR/link.sh" --check 2>&1)"; then + ok "knowledge bundles linked from $KNOWLEDGE_DIR" + else + bad "knowledge bundle links out of sync" + grep -v '✓' <<<"$links" | detail + hint "$KNOWLEDGE_DIR/link.sh" + fi +else + ok "no private knowledge repo at $KNOWLEDGE_DIR (optional)" +fi + # --------------------------------------------------------------------------- section "Environment" # --------------------------------------------------------------------------- diff --git a/lib.sh b/lib.sh index 040af94..698cc1c 100644 --- a/lib.sh +++ b/lib.sh @@ -20,6 +20,13 @@ STOW_PACKAGES=(zsh git tmux ghostty nvim claude) # every key or known_hosts file written there would land in the working tree. SSH_STOW_OPTS=(--no-folding) +# Private repo holding Claude Code's OKF knowledge bundles. bootstrap clones it +# when the GitHub account can see it and runs its link.sh, which symlinks each +# bundle into place; doctor runs link.sh --check. Optional: a fork without +# access skips it. +KNOWLEDGE_REPO="jpmontez/knowledge" +KNOWLEDGE_DIR="$HOME/Development/knowledge" + if [[ "$(uname)" == "Darwin" ]]; then PLATFORM="macos" else From 8c1b1cfe11c4d41aefc87a30f3359a974b69aa27 Mon Sep 17 00:00:00 2001 From: Julian Montez Date: Sun, 4 Oct 2026 11:53:46 -0400 Subject: [PATCH 2/3] Clone the knowledge repo without running or linking anything from it Drops the link.sh call from bootstrap and doctor. bootstrap only clones; doctor reads the clone's origin and flags a mismatch. Bundles are read from ~/Development/knowledge by directory name, so no symlink to private knowledge sits inside a public repo. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 5 ++--- README.md | 15 +++++++-------- bootstrap.sh | 4 ---- doctor.sh | 13 +++++++------ lib.sh | 6 +++--- 5 files changed, 19 insertions(+), 24 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b12471f..dc3556a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,9 +11,8 @@ Personal dotfiles managed with GNU stow. Full details: README.md. `doctor.sh` is read-only drift detection only — never edits anything. - `KNOWLEDGE_REPO`/`KNOWLEDGE_DIR` in `lib.sh` point at the private OKF - knowledge repo; bootstrap clones it and runs its `link.sh`, doctor runs - `link.sh --check`. Never commit a `knowledge/` directory here: it is a - symlink hidden through `.git/info/exclude`. + knowledge repo; bootstrap clones it and doctor checks its origin. Never run + code from it, and never add a `knowledge/` directory or link here. ## Conventions - New dotfile: create/extend a package dir mirroring `$HOME`, then add the diff --git a/README.md b/README.md index a59bac5..4d3caec 100644 --- a/README.md +++ b/README.md @@ -123,14 +123,13 @@ repo. `doctor.sh` flags it if it ever folds back. Claude Code's [Open Knowledge Format](https://github.com/GoogleCloudPlatform/open-knowledge-format) bundles live in a separate private repo, `jpmontez/knowledge`, cloned to -`~/Development/knowledge`. Its `link.sh` symlinks each bundle to where sessions -look for it (`/knowledge`, `~/.claude/knowledge`) and hides the links -through each repo's `.git/info/exclude`, so nothing from it lands in this or any -other public repo. +`~/Development/knowledge`. Claude Code reads them from there by directory name; +nothing from it is linked into this or any other repo, and nothing in it is +executed. -Bootstrap clones it when `gh` is signed in with access and runs `link.sh`; -otherwise it skips the step. `doctor.sh` runs `link.sh --check`. It's optional, -so a fork without access loses nothing. +Bootstrap clones it when `gh` is signed in with access, and otherwise skips the +step. `doctor.sh` checks the clone's origin. It's optional, so a fork without +access loses nothing. --- @@ -148,7 +147,7 @@ so a fork without access loses nothing. ## Post-Install 1. **SSH keys** — copy or generate into `~/.ssh/` (`ssh-keygen -t ed25519`). It's a real directory, so keys stay out of the working tree. -2. **GitHub CLI** — `gh auth login`, then re-run `./bootstrap.sh` to clone and link the private knowledge repo. +2. **GitHub CLI** — `gh auth login`, then re-run `./bootstrap.sh` to clone the private knowledge repo. 3. **App Store** — sign in, then re-run `brew bundle` if `mas` entries were skipped. 4. **tmux plugins** — TPM auto-installs on first launch; `prefix + I` after adding plugins later. 5. **Check your work** — `./doctor.sh` should come back clean. diff --git a/bootstrap.sh b/bootstrap.sh index 6589528..72d0b09 100755 --- a/bootstrap.sh +++ b/bootstrap.sh @@ -210,10 +210,6 @@ if [[ ! -d "$KNOWLEDGE_DIR" ]]; then echo ">>> Skipping $KNOWLEDGE_REPO (not signed in to gh, or no access). Re-run after gh auth login." fi fi -if [[ -x "$KNOWLEDGE_DIR/link.sh" ]]; then - echo ">>> Linking knowledge bundles..." - "$KNOWLEDGE_DIR/link.sh" || echo ">>> Warning: some knowledge links need attention (see above)." -fi # ---- macOS system defaults ---- applied_defaults=0 diff --git a/doctor.sh b/doctor.sh index 1be0a41..c36fc0b 100755 --- a/doctor.sh +++ b/doctor.sh @@ -142,13 +142,14 @@ else ok "working tree clean" fi -if [[ -x "$KNOWLEDGE_DIR/link.sh" ]]; then - if links="$("$KNOWLEDGE_DIR/link.sh" --check 2>&1)"; then - ok "knowledge bundles linked from $KNOWLEDGE_DIR" +# Read-only: compares the clone's origin and never runs anything from it. +if [[ -d "$KNOWLEDGE_DIR/.git" ]]; then + origin="$(git -C "$KNOWLEDGE_DIR" remote get-url origin 2>/dev/null || true)" + if [[ "$origin" =~ github\.com[:/]${KNOWLEDGE_REPO}(\.git)?$ ]]; then + ok "knowledge repo $KNOWLEDGE_REPO at $KNOWLEDGE_DIR" else - bad "knowledge bundle links out of sync" - grep -v '✓' <<<"$links" | detail - hint "$KNOWLEDGE_DIR/link.sh" + bad "$KNOWLEDGE_DIR has origin '${origin:-none}', want $KNOWLEDGE_REPO" + hint "git -C $KNOWLEDGE_DIR remote -v" fi else ok "no private knowledge repo at $KNOWLEDGE_DIR (optional)" diff --git a/lib.sh b/lib.sh index 698cc1c..930b30d 100644 --- a/lib.sh +++ b/lib.sh @@ -21,9 +21,9 @@ STOW_PACKAGES=(zsh git tmux ghostty nvim claude) SSH_STOW_OPTS=(--no-folding) # Private repo holding Claude Code's OKF knowledge bundles. bootstrap clones it -# when the GitHub account can see it and runs its link.sh, which symlinks each -# bundle into place; doctor runs link.sh --check. Optional: a fork without -# access skips it. +# when the GitHub account can see it; doctor checks the clone's origin. Nothing +# in it is executed or linked into place. Optional: a fork without access skips +# it. KNOWLEDGE_REPO="jpmontez/knowledge" KNOWLEDGE_DIR="$HOME/Development/knowledge" From 965fb5cac3d04a01d043d806ce69192c4ed96e8b Mon Sep 17 00:00:00 2001 From: Julian Montez Date: Sun, 4 Oct 2026 11:56:56 -0400 Subject: [PATCH 3/3] doctor: strip credentials from the knowledge repo's origin before printing it Co-Authored-By: Claude Opus 5.5 --- doctor.sh | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doctor.sh b/doctor.sh index c36fc0b..ae1f5ae 100755 --- a/doctor.sh +++ b/doctor.sh @@ -144,7 +144,8 @@ fi # Read-only: compares the clone's origin and never runs anything from it. if [[ -d "$KNOWLEDGE_DIR/.git" ]]; then - origin="$(git -C "$KNOWLEDGE_DIR" remote get-url origin 2>/dev/null || true)" + # Strip any user:token@ before the URL is compared or printed. + origin="$(git -C "$KNOWLEDGE_DIR" remote get-url origin 2>/dev/null | sed -E 's#^([a-z+]+://)[^/@]*@#\1#' || true)" if [[ "$origin" =~ github\.com[:/]${KNOWLEDGE_REPO}(\.git)?$ ]]; then ok "knowledge repo $KNOWLEDGE_REPO at $KNOWLEDGE_DIR" else