| name | graincrawl |
| description | Maintain, verify, and release graincrawl, the local-first Granola archive CLI, including SQLite archive behavior, read-only Granola source boundaries, Homebrew tap packaging, and crawlkit-powered TUI/snapshot surfaces. |
| license | MIT |
| metadata | {"source":"https://github.com/vincentkoc/dotskills"} |
Graincrawl
Purpose
Maintain graincrawl, the Go CLI that archives Granola notes, transcripts,
panels, people, workspaces, and sync metadata into a private local SQLite store.
Keep it read-only against Granola, SQLite-first for browsing/export, and aligned
with the other crawl apps.
When to use
- Editing or reviewing a
graincrawl checkout.
- Investigating Granola source adapters:
private-api, desktop-cache,
encrypted-json, opfs, public-api, or companion-cli.
- Verifying note, transcript, panel, source object, search, Markdown export, or
TUI behavior.
- Preparing a
graincrawl release, Homebrew formula, or local binary refresh.
- Checking crawlkit control metadata, snapshots, or TUI integration from the app
side.
Workflow
-
Locate the graincrawl checkout from the current repository, an explicit
user path, or the configured workspace root. Read repo-local AGENTS.md, README.md, SPEC.md, and
docs/security.md before release, source-adapter, or unlock work.
-
Keep Granola boundaries explicit. Ordinary doctor, status, notes,
export, and tui commands must not prompt Keychain, unwrap safeStorage, or
mutate Granola profile files.
-
Use temp HOME, temp XDG dirs, temp config, and temp SQLite databases for
tests and smoke checks. Do not mutate live ~/.config/graincrawl archives or
Granola app data unless the user explicitly asks.
-
Prefer archived SQLite reads for UI/export behavior. If Markdown export has
the data, TUI detail should read that same archived source, not re-query
Granola.
-
Run the normal local gate with workspace masking disabled:
GOWORK=off go mod tidy
git diff --exit-code -- go.mod go.sum
GOWORK=off go vet ./...
GOWORK=off go test -count=1 ./...
make smoke
goreleaser check
-
For release work, use semver tags and verify the tap path:
git tag -a v0.1.0 -m "graincrawl v0.1.0"
git push origin main v0.1.0
HOMEBREW_NO_AUTO_UPDATE=1 brew install --build-from-source vincentkoc/tap/graincrawl
HOMEBREW_NO_AUTO_UPDATE=1 brew test vincentkoc/tap/graincrawl
-
After app changes, refresh the local binary when requested or when handing
off a testable CLI:
GOWORK=off go build -trimpath -o ~/.local/bin/graincrawl ./cmd/graincrawl
graincrawl version --json
Inputs
- Target task: app edit, source-adapter investigation, local archive/TUI fix,
release verification, tap update, or binary refresh.
- Optional version tag such as
v0.1.0.
- Optional temp fixture paths or a copied Granola profile for encrypted/OPFS
investigation.
Outputs
- A focused graincrawl change or readiness report.
- Validation commands and results.
- Explicit notes about any private API, Keychain, safeStorage, OPFS, or live
profile boundary crossed.
- Tap/release status and local binary path when release or install work is in
scope.
