cribsheet 0.2.0__tar.gz

cribsheet-0.2.0/.claude-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "name": "cribsheet",
+  "owner": {
+    "name": "George Harker",
+    "email": "george@georgeharker.com"
+  },
+  "plugins": [
+    {
+      "name": "cribsheet",
+      "source": "./plugins/cribsheet",
+      "description": "Persistent markdown memory + a code symbol index (concept/name lookup, call graph, references, learnings) for your AI. Registers the crib MCP server via sharedserver (respects a global install; skip with CRIB_EXTERNAL) and carries the reach-for-crib instructions."
+    },
+    {
+      "name": "cribsheet-instructions",
+      "source": "./plugins/cribsheet-instructions",
+      "description": "Instructions only — the 'prefer the code index over grep, consult/store memory' directives, injected each session. No MCP registration. For when crib's tools already reach you another way (e.g. via mcp-combiner)."
+    }
+  ]
+}

cribsheet-0.2.0/.crib

@@ -0,0 +1,7 @@
+project: cribsheet        # this repo's own crib namespace
+import:                   # design docs to ingest (one-way pull; source wins on re-import)
+  - DESIGN.md
+  - docs/**/*.md
+  - README.md
+refs:                     # cross-project xref: resolve llmkit symbols + attribute
+  - llmkit                # edges into ~/Development/llmkit's own index

cribsheet-0.2.0/.github/workflows/docs-on-change.yml

@@ -0,0 +1,31 @@
+# Thin caller for gh-quarto-publish: deploy docs when they change on a branch.
+name: docs (branch push)
+
+on:
+  workflow_dispatch:   # manual run: deploys the selected branch to its prefix
+  push:
+    branches: [main]
+    paths:
+      - "README.md"
+      - "index.md"
+      - "DESIGN.md"
+      - "docs/**"
+      - "_quarto.yml"
+      - ".github/workflows/docs-on-change.yml"
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    # Inert until the deploy vars/secrets are configured on the repo.
+    if: ${{ vars.DOCS_SSH_DEST != '' }}
+    uses: georgeharker/gh-quarto-publish/.github/workflows/publish.yml@main
+    with:
+      target-prefix: ${{ github.ref_name }}
+      ssh-dest: ${{ vars.DOCS_SSH_DEST }}
+      site-url: ${{ vars.DOCS_SITE_URL }}
+    secrets:
+      deploy-key: ${{ secrets.DOCS_DEPLOY_KEY }}
+      host-key: ${{ secrets.DOCS_HOST_KEY }}

cribsheet-0.2.0/.github/workflows/docs-on-tag.yml

@@ -0,0 +1,25 @@
+# Thin caller for gh-quarto-publish: refresh the default-branch docs when a
+# release tag is pushed.
+name: docs (release tag)
+
+on:
+  push:
+    tags: ["v*"]
+
+concurrency:
+  group: docs-refs/heads/main
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    # Inert until the deploy vars/secrets are configured on the repo.
+    if: ${{ vars.DOCS_SSH_DEST != '' }}
+    uses: georgeharker/gh-quarto-publish/.github/workflows/publish.yml@main
+    with:
+      # Tags are cut from the default branch; releases refresh its docs.
+      target-prefix: main
+      ssh-dest: ${{ vars.DOCS_SSH_DEST }}
+      site-url: ${{ vars.DOCS_SITE_URL }}
+    secrets:
+      deploy-key: ${{ secrets.DOCS_DEPLOY_KEY }}
+      host-key: ${{ secrets.DOCS_HOST_KEY }}

cribsheet-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,86 @@
+name: Release (cribsheet)
+
+# Publishes the `cribsheet` package to PyPI when a version tag is pushed:
+#   git tag v0.1.0 && git push origin v0.1.0
+#
+# NOTE: cribsheet depends on `polyllmkit` from PyPI, so publish polyllmkit FIRST
+# (georgeharker/llmkit release.yml) or this build resolves nothing to install.
+#
+# Auth — pick one in the `publish` job below:
+#   A) Trusted Publishing (OIDC) — DEFAULT, no secrets. One-time PyPI setup at
+#      https://pypi.org/manage/account/publishing/ (pending publisher), with:
+#         PyPI project:  cribsheet
+#         owner/repo:    georgeharker/cribsheet
+#         workflow:      release.yml
+#         environment:   pypi
+#   B) API token — set repo secret PYPI_API_TOKEN and uncomment `password:` below.
+#
+# Create a GitHub environment named "pypi" (Settings -> Environments) to gate
+# releases with required reviewers (recommended for both options).
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # The version lives in ONE place — pyproject.toml; __version__ is derived
+      # from it at runtime via importlib.metadata. The tag is the only other
+      # location, so refuse to release when it doesn't match the source.
+      - name: Verify tag matches pyproject version
+        run: |
+          pkg="$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
+          tag="${GITHUB_REF_NAME#v}"
+          if [ "$pkg" != "$tag" ]; then
+            echo "::error::tag v$tag does not match pyproject version $pkg — bump pyproject.toml in the release commit"
+            exit 1
+          fi
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Build sdist + wheel
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write          # required for option A (Trusted Publishing / OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # Option A (trusted publishing): leave `password` unset — OIDC is used automatically.
+          # Option B (API token): uncomment the next line and set the PYPI_API_TOKEN secret.
+          # password: ${{ secrets.PYPI_API_TOKEN }}
+          # TestPyPI instead? add:  repository-url: https://test.pypi.org/legacy/
+          attestations: true
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write          # required to create the GitHub Release
+    steps:
+      - uses: actions/checkout@v4   # for --generate-notes (needs the tag + history)
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        # --generate-notes auto-builds notes from merged PRs/commits since the previous tag;
+        # the built sdist + wheel are attached as downloadable assets.
+        run: gh release create "${GITHUB_REF_NAME}" dist/* --title "${GITHUB_REF_NAME}" --generate-notes

cribsheet-0.2.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+
+# crib runtime state, if a data dir ever lives in-tree
+.versions/
+/.DS_Store
+
+# Quarto docs site (generated)
+/_site/
+/.quarto/
+
+**/*.quarto_ipynb

cribsheet-0.2.0/.gitmodules

@@ -0,0 +1,4 @@
+[submodule "vendor/llmkit"]
+	path = vendor/llmkit
+	url = https://github.com/georgeharker/llmkit.git
+	branch = main

cribsheet-0.2.0/CLAUDE.md.example

@@ -0,0 +1,36 @@
+# Memory (cribsheet)
+
+<!-- Canonical reach-for-crib directive. Copy into your global
+     $CLAUDE_CONFIG_DIR/CLAUDE.md, or let a cribsheet plugin inject it each session
+     (the plugins symlink this file). It directs *approach*; the MCP tool
+     descriptions carry the mechanics. -->
+
+- **Consult memory first.** Before answering about a project, topic, or past decision
+  — or exploring a codebase cold — `lookup`/`apropos` cribsheet first; the answer may
+  already be stored, and more current than reasoning from scratch.
+- **Prefer the code index over grep/Read for understanding code.** The reflex to
+  `grep`/`rg`/`Glob` for a symbol — or to open a file to see what it does — is the cue
+  to reach for the index first; grep is the fallback when it misses, not the default.
+    - *find code by concept or name* → `code_lookup "…in your own words"`, **not**
+      `grep -r` (answers by intent + cross-file).
+    - *understand a symbol + who uses it* → `code_dossier <symbol>`, **not** reading
+      the whole file (one call: signature, description, callers/callees/references).
+    - *trace calls* → `code_xref` / `code_graph`, **not** chains of greps.
+    - *repo not indexed?* → that's the expected first step, not a dead end: **index it**
+      — `project_index` (indexes the source in one call), then look up. Do NOT read
+      files or grep instead; there's no shortcut, the utility comes from the index.
+    - *which project?* → code tools act on ONE **current project**. Set it once for the
+      codebase you're in (`use_project <name>`, or it's inferred from `project_path` on
+      your first code call); reads then need no project args. To look up a **different**
+      project (a related codebase you're referencing), you MUST name it: `project=<name>`
+      or `project_path=<a path in that repo>`. (`project_path` ≠ your shell cwd — it just
+      says which repo you mean.)
+  E.g. not `grep -rn "def boolean"` then reading the file — `code_lookup "boolean path
+  union/difference"` → `code_dossier` the top hit. (When you finally *get* a tricky
+  symbol, `code_append <symbol> "…"` pins that understanding for next time.)
+- **Persist durably.** When a durable fact emerges (a decision, convention, gotcha,
+  contract), `store` it — `lookup` first, `append`/`edit` over duplicating. **Name the
+  project it's ABOUT** (writes require an explicit `project=`/`project_path=` — they
+  won't inherit your current one): a fact about the repo you're in goes there, but
+  cross-cutting/tooling knowledge (a CLI, an editor, a shared convention) belongs in
+  `default` or that tool's own project. Say which project it landed in.