claude-wiki 0.1.0__tar.gz

claude_wiki-0.1.0/.claude/skills/claude-wiki/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: claude-wiki
+description: |-
+  Bootstrap and manage the claude-wiki knowledge base for this repo.
+  Covers init, shared rules, safety, and Makefile targets.
+  For specific commands, invoke the dedicated /claude-wiki-<command> skills.
+---
+
+# claude-wiki
+
+Knowledge base bootstrap and shared reference.
+
+## Init
+
+**Trigger**: "set up knowledge base", "init claude-wiki", "configure KB for this repo"
+
+Run from the repo root after confirming it is a git repo.
+
+1. Run `claude-wiki init`
+1. By default hooks go into repo-local `.claude/settings.local.json`
+1. If user wants user-wide hooks, add `--global` (writes to `~/.claude/settings.json`)
+1. Completion: `.claude-wiki.lock` exists in repo root, repo appears in `~/.local/share/claude-wiki/core.md`
+
+## Other Commands
+
+Invoke the dedicated skill when needed:
+
+- `/claude-wiki-compile` — compile daily logs into knowledge
+- `/claude-wiki-query` — search and ask the knowledge base
+- `/claude-wiki-lint` — run health checks on the KB
+- `/claude-wiki-migrate` — move data when config paths change
+
+## Rules
+
+- Run from within the target repo root; `init`, `migrate`, and `compile` accept `--path <repo-root>`
+- After any config edit to `kb_dir` or `daily_dir`, run `migrate --dry-run` before `migrate`
+- Do not hand-edit `daily/` files — they are append-only
+- Do not hand-edit `~/.local/share/claude-wiki/.registry.json` or `~/.local/share/claude-wiki/core.md` — they are machine-managed
+
+## Safety
+
+| Command         | Destructive?                   | Mitigation                                                        |
+| --------------- | ------------------------------ | ----------------------------------------------------------------- |
+| `init --force`  | Overwrites `.claude-wiki.lock` | Paths compared from the lock file itself; no secondary state file |
+| `migrate`       | Moves directories              | `--dry-run` preview; warns and skips non-empty dest               |
+| `compile --all` | Rebuilds entire KB             | Idempotent — recompiles from immutable daily                      |
+| `lint`          | Read-only                      | None needed                                                       |
+
+## Global Registry
+
+Every `init`, `compile`, and `migrate` registers the repo in `~/.local/share/claude-wiki/core.md` and auto-evicts stale entries (repos whose `.claude-wiki.lock` has disappeared).
+
+## Makefile Targets
+
+```bash
+make dev        # install with dev dependencies
+make test       # run pytest
+make lint       # ruff check
+make format     # ruff format + mdformat
+make typecheck  # mypy
+make precommit  # all pre-commit hooks
+make all        # full CI gate
+make build      # build wheel
+make clean      # remove artifacts
+```
+
+## Cost Reference
+
+| Operation              | Approximate |
+| ---------------------- | ----------- |
+| compile one log        | $0.45–0.65  |
+| query (no file-back)   | $0.15–0.25  |
+| query (with file-back) | $0.25–0.40  |
+| full lint (with LLM)   | $0.15–0.25  |
+| structural lint only   | $0.00       |

claude_wiki-0.1.0/.claude/skills/claude-wiki-compile/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: claude-wiki-compile
+description: Compile daily conversation logs into structured knowledge base articles. Invoke with /claude-wiki-compile.
+disable-model-invocation: true
+---
+
+# claude-wiki compile
+
+Turn immutable `daily/` logs into structured KB articles.
+
+## Trigger
+
+- "compile today's logs"
+- "build the KB"
+- "sync knowledge"
+- "run compile"
+
+## Process
+
+1. Run `claude-wiki compile`
+1. If user asks for full rebuild, add `--all`
+1. If user wants one specific log, add `--file daily/YYYY-MM-DD.md`
+1. If user wants a preview, add `--dry-run`
+1. Completion: `knowledge/index.md` reflects latest daily log, global registry updated.
+
+## Flags
+
+| Flag            | Purpose                                       |
+| --------------- | --------------------------------------------- |
+| `--all`         | Force recompile entire KB from all daily logs |
+| `--file <path>` | Compile a single daily log                    |
+| `--dry-run`     | Preview what would compile without writing    |
+
+## Rules
+
+- Compilation is idempotent — re-running on the same log produces the same articles (deduplicated by hash)
+- Do not hand-edit `daily/` files — they are append-only and the source of truth
+- The KB lives under the XDG data dir by default (`~/.local/share/claude-wiki/<owner>/<repo>/`)
+
+## Completion
+
+- `knowledge/index.md` updated with new article links
+- `knowledge/concepts/`, `connections/`, `qa/` populated or updated
+- Global registry entry refreshed

claude_wiki-0.1.0/.claude/skills/claude-wiki-dev/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: claude-wiki-dev
+description: |
+  Develop and maintain the claude-wiki package itself.
+  Use when modifying CLI commands, hook handlers, migration logic, or adding new features.
+  Covers project structure, testing patterns, and release workflow.
+disable-model-invocation: true
+---
+
+# claude-wiki dev
+
+Development reference for the claude-wiki package.
+
+## Project Structure
+
+```
+src/claude_wiki/
+  cli.py              # argparse main + subcommand dispatch
+  config.py           # ConfigManager (repo detection, lock I/O, XDG resolution)
+  factories.py        # DefaultConfigResolver wiring
+  flush.py            # Shared context extraction + background flush logic
+  global_index.py     # ~/.local/share/claude-wiki registry
+  hooks.py            # Hook dispatcher (SessionStart, SessionEnd, PreCompact)
+  interfaces.py       # Protocol definitions (RepoDetector, ConfigLoader, etc.)
+  migration.py        # MigrationManager (path change detection + data move)
+  models.py           # Immutable dataclasses (ProjectConfig, MigrationResult, etc.)
+  commands/           # Dynamically loaded subcommands
+    compile.py
+    lint.py
+    query.py
+  hook_handlers/      # Per-event handler modules
+    session_start.py
+    session_end.py
+    pre_compact.py
+tests/                # pytest suite
+docs/                 # Documentation
+.claude/skills/        # Claude Code skills for this repo
+```
+
+## Setup
+
+```bash
+make dev        # install package with dev deps (uv pip install -e ".[dev]")
+```
+
+Requires Python >=3.12.
+
+## Development Cycle
+
+```bash
+make format     # ruff format + mdformat skills/docs
+make lint       # ruff check
+make typecheck  # mypy --strict src/
+make test       # pytest
+make test-cov   # pytest with coverage
+make all        # format + lint + typecheck + test + precommit (full CI gate)
+```
+
+## Adding a New CLI Command
+
+1. Create `src/claude_wiki/commands/<command>.py`
+1. Implement `register(subparsers, handlers)` function
+1. Optionally create `tests/test_<command>.py`
+1. Optionally create `.claude/skills/claude-wiki-<command>/SKILL.md`
+1. Register is auto-discovered by `cli._register_commands()` via `pkgutil`
+
+## Hook Architecture
+
+- `hooks.py` dispatches to handler modules by event name
+- Each handler in `hook_handlers/` exports `handler(args) -> int` and `register(handlers: dict)`
+- Handlers do fast local I/O only; heavy work is spawned to `flush.py` background process
+- Recursion guard: `CLAUDE_INVOKED_BY` env var prevents nested hook triggers
+
+## Testing Patterns
+
+- Use `tempfile.TemporaryDirectory()` for CLI integration tests
+- Use `tmp_path` pytest fixture for unit tests
+- Patch `os.environ` for HOME/XDG overrides
+- Mock `claude_wiki.cli.GlobalIndexManager` to avoid filesystem side effects
+- Tests must be deterministic — no external network calls in tests
+
+## Config & State
+
+- `.claude-wiki.lock` is the single source of truth for repo config
+- No secondary state file (`.claude-wiki.state.json` was removed)
+- Migration compares current lock against previous by loading it as `previous`
+- XDG data dir: `~/.local/share/claude-wiki/<owner>/<repo>/`
+
+## Release
+
+```bash
+make build      # uv build (wheel in dist/)
+make pypi-start # local PyPI registry on :8080 for smoke testing
+make pypi-stop  # tear down local registry
+```
+
+## Conventions
+
+- **Commits**: conventional commits (`feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`)
+- **Branches**: `feat/`, `fix/`, `chore/`, `docs/`, `refactor/`, `test/`, `ci/` prefix
+- **Imports**: `from __future__ import annotations` at top; absolute imports preferred
+- **Types**: `mypy --strict` required; annotate all public APIs
+- **Formatting**: ruff format + mdformat with `mdformat-frontmatter` and `mdformat-gfm`

claude_wiki-0.1.0/.claude/skills/claude-wiki-lint/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: claude-wiki-lint
+description: Run health checks on the knowledge base. Invoke with /claude-wiki-lint.
+disable-model-invocation: true
+---
+
+# claude-wiki lint
+
+Structural and LLM-based health checks for the KB.
+
+## Trigger
+
+- "lint the knowledge base"
+- "check KB health"
+- "find broken links"
+- "run wiki lint"
+
+## Process
+
+1. Run `claude-wiki lint`
+1. For structural-only (no LLM cost), add `--structural-only`
+1. Completion: report printed or report file path shown.
+
+## Checks
+
+| Check           | Severity   | What it finds                                |
+| --------------- | ---------- | -------------------------------------------- |
+| Broken links    | Error      | `[[wikilinks]]` pointing to missing articles |
+| Orphan pages    | Warning    | Articles with zero inbound links             |
+| Orphan sources  | Warning    | Daily logs not yet compiled                  |
+| Stale articles  | Warning    | Daily logs changed since last compile        |
+| Sparse articles | Suggestion | Articles below 200 words                     |
+| Contradictions  | Warning    | Cross-article conflicts (LLM-only)           |
+
+## Flags
+
+| Flag                | Purpose                                      |
+| ------------------- | -------------------------------------------- |
+| `--structural-only` | Skip LLM contradiction checks (free, faster) |
+
+## Rules
+
+- Reports are saved to `knowledge/reports/` (or the configured `reports_dir`) as `lint-YYYY-MM-DD.md`
+- Structural checks are deterministic and free; contradiction checks cost ~$0.15–0.25
+- Warnings do not fail the lint exit code; errors do
+
+## Completion
+
+- Terminal shows error/warning/suggestion counts
+- Report path printed (e.g., `knowledge/reports/lint-2026-06-19.md`)

claude_wiki-0.1.0/.claude/skills/claude-wiki-migrate/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: claude-wiki-migrate
+description: Migrate knowledge base data when config paths change. Invoke with /claude-wiki-migrate.
+disable-model-invocation: true
+---
+
+# claude-wiki migrate
+
+Move data when kb_dir, daily_dir, or reports_dir change.
+
+## Trigger
+
+- "moved KB directory"
+- "changed daily_dir"
+- "migrate wiki data"
+- "change knowledge path"
+
+## Process
+
+1. Run claude-wiki migrate --dry-run first
+1. Review output — confirm paths and absence of errors
+1. Run claude-wiki migrate to execute
+1. Completion: --dry-run showed expected moves; actual run reports "State updated." when paths changed, or "No migration needed — paths are unchanged."
+
+## Flags
+
+| Flag                   | Purpose                                       |
+| ---------------------- | --------------------------------------------- |
+| `--dry-run`            | Preview what would move without touching disk |
+| `--kb-dir <path>`      | Override knowledge base directory             |
+| `--daily-dir <path>`   | Override daily log directory                  |
+| `--reports-dir <path>` | Override lint reports directory               |
+
+## Rules
+
+- --dry-run is mandatory before a real migration; review warnings carefully
+- Migration refuses to proceed if new kb_dir and daily_dir would overlap
+- If destination already exists and is not empty, the move is skipped with a warning
+- After migration, .claude-wiki.lock is rewritten with the new paths
+- The lock file itself serves as the previous-state reference; no secondary state file is maintained
+
+## Completion
+
+- Data moved from old paths to new paths (or skipped if destination occupied)
+- .claude-wiki.lock updated with new directory paths
+- Global registry updated if kb_dir changed

claude_wiki-0.1.0/.claude/skills/claude-wiki-query/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: claude-wiki-query
+description: Search and query the accumulated knowledge base. Invoke with /claude-wiki-query.
+disable-model-invocation: true
+---
+
+# claude-wiki query
+
+Ask the knowledge base natural-language questions.
+
+## Trigger
+
+- "search my KB"
+- "what do I know about..."
+- "ask the knowledge base"
+- "query wiki"
+
+## Process
+
+1. Formulate the query as a single quoted string
+1. Run `claude-wiki query "<question>"`
+1. If user wants the answer saved back to KB, add `--file-back`
+1. Completion: answer printed, and `--file-back` creates `qa/` article and updates `index.md`.
+
+## Flags
+
+| Flag          | Purpose                                                      |
+| ------------- | ------------------------------------------------------------ |
+| `--file-back` | Save the answer as a new `qa/` article and update `index.md` |
+
+## Rules
+
+- Queries are index-guided — the LLM reads `knowledge/index.md` first, then drills into relevant articles
+- No RAG or vector search is used; retrieval relies on the human-maintained index and cross-links
+- `--file-back` compounds knowledge: each saved answer becomes available to future queries
+
+## Completion
+
+- Answer printed to stdout with inline citations
+- With `--file-back`: new article in `knowledge/qa/` and updated `index.md`

claude_wiki-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns:
+          - "*"

claude_wiki-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,72 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: uv sync --extra dev --frozen
+
+      - name: Run tests
+        run: uv run pytest tests/ -v
+
+      - name: Run ruff check
+        run: uvx ruff check .
+
+      - name: Run ruff format check
+        run: uvx ruff format --check .
+
+      - name: Run mypy
+        run: uv run mypy src/
+
+      - name: Check markdown formatting
+        run: |
+          uvx --with mdformat-frontmatter --with mdformat-gfm mdformat --check \
+            docs/ README.md src/claude_wiki/AGENTS.md .claude/skills/claude-wiki/SKILL.md
+
+  precommit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.12"
+
+      - name: Sync dependencies
+        run: uv sync --extra dev --frozen
+
+      - name: Run pre-commit
+        run: uv run pre-commit run --all-files

claude_wiki-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,67 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: "Publish to PyPI (requires trusted publisher setup)"
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch' && inputs.publish == true
+    environment:
+      name: pypi
+      url: https://pypi.org/project/claude-wiki/${{ github.ref_name }}
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Download artifacts
+        uses: actions/download-artifact@b14cf4c92620c250e1c074ab0a5800e37df86765 # v4.2.0
+        with:
+          name: dist
+          path: dist/
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          version: "latest"
+
+      - name: Publish to PyPI
+        run: uv publish dist/*

claude_wiki-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.venv/
+.env
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg
+*.whl
+.DS_Store
+*.log
+.claude/worktrees/
+.claude/settings.local.json
+reports/lint-*.md
+bin/
+*.code-workspace

claude_wiki-0.1.0/.gitleaks.toml

@@ -0,0 +1,10 @@
+title = "claude-wiki gitleaks config"
+
+[extend]
+useDefault = true
+
+[allowlist]
+paths = [
+    '''\.gitleaks\.toml''',
+    '''\.claude-wiki\.state\.json''',
+]

claude_wiki-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,55 @@
+repos:
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1
+    hooks:
+      - id: gitleaks
+        name: Scan for secrets
+        stages: [pre-commit]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.18
+    hooks:
+      - id: ruff
+        name: Lint with ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+        name: Check formatting with ruff
+
+  - repo: https://github.com/executablebooks/mdformat
+    rev: 1.0.0
+    hooks:
+      - id: mdformat
+        name: Check markdown formatting
+        additional_dependencies:
+          - mdformat-frontmatter
+          - mdformat-gfm
+        args: [--check]
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v2.1.0
+    hooks:
+      - id: mypy
+        name: Type check with mypy
+        additional_dependencies:
+          - types-python-dateutil
+        pass_filenames: false
+        always_run: true
+        args: [src/]
+
+  - repo: local
+    hooks:
+      - id: pytest
+        name: Run pytest
+        entry: uv run pytest
+        language: system
+        types: [python]
+        pass_filenames: false
+        always_run: true
+        stages: [pre-commit]
+
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v4.4.0
+    hooks:
+      - id: conventional-pre-commit
+        name: Validate conventional commit message
+        stages: [commit-msg]

claude_wiki-0.1.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [unreleased]
+
+### Added
+
+- Claude-wiki knowledge base system
+- Add migration mechanism for config path changes
+- Global knowledge base registry
+- Auto-evict stale entries from global registry
+- Init defaults to repo-local hooks, --global for user-wide
+- Add migrate path overrides, split skills, and remove state file
+
+### Changed
+
+- Normalize naming — marker, package, and docs
+- Rename global registry index to core.md
+
+### Documentation
+
+- Audit and fix drift across all docs and skill
+- Update install and contributor guides for uv sync
+- Add CHANGELOG.md
+- Release v0.1.0
+
+### Fixed
+
+- Resolve gap-analysis blockers and flatten kb_dir resolution
+
+### Maintenance
+
+- Add pre-commit hooks and align dependencies
+- Add Makefile and fix README stale references
+- Add GitHub workflows, local PyPI registry, and act support
+- Update workflows to 2026 standards with SHA pinning
+- Add mypy to dev dependencies for CI type-check gate
+- Add cliff.toml for automated CHANGELOG generation
+
+## Earlier Work
+
+See git log for the full commit history prior to formal changelog adoption.

claude_wiki-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mister Robot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.