akashic-kb 0.1.0__tar.gz

akashic_kb-0.1.0/.akashic/config.yaml

@@ -0,0 +1,11 @@
+version: 1
+knowledge:
+  path: .
+repositories: []
+agent:
+  provider: codex
+  command: null
+site:
+  port: 6969
+generation:
+  model: null

akashic_kb-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.scratch
+.env
+.venv
+__pycache__/
+.pytest_cache/
+.akashic/cache/
+.akashic/logs/
+.akashic/config.local.yaml
+node_modules/
+dist/
+node_modules

akashic_kb-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akashic contributors
+
+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.

akashic_kb-0.1.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: akashic-kb
+Version: 0.1.0
+Summary: CLI for Git-backed knowledge repositories.
+Project-URL: Homepage, https://github.com/kanakOS01/akashic
+Project-URL: Repository, https://github.com/kanakOS01/akashic
+Project-URL: Issues, https://github.com/kanakOS01/akashic/issues
+Project-URL: Documentation, https://github.com/kanakOS01/akashic/tree/main/docs
+Author: Akashic contributors
+License: MIT License
+        
+        Copyright (c) 2026 Akashic contributors
+        
+        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.
+License-File: LICENSE
+Keywords: cli,documentation,git,knowledge-base,markdown
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2
+Requires-Dist: pyyaml>=6
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Akashic
+
+Akashic is a local-first CLI for Git-backed knowledge repositories. It helps
+teams keep structured Markdown documentation beside real source repositories,
+then browse that documentation through a local web UI.
+
+Akashic does not analyze code by itself. It manages the knowledge repo,
+discovers attached source repos, builds generation prompts, and hands those
+prompts to an agent provider such as Codex or Claude.
+
+## Features
+
+- Initialize a Git-backed knowledge repository.
+- Attach one or more local Git source repositories.
+- Generate structured docs for services, flows, system notes, ADRs, entities,
+  and glossary entries.
+- Preserve hand-written content through `<!-- HUMAN:START -->` sections.
+- Serve docs through a local React/Vite site.
+- Build a static read-only docs site.
+- Validate setup with `doctor` and inspect repo state with `status`.
+
+## Installation
+
+Akashic is a Python package targeting Python 3.10+.
+
+Install the released CLI:
+
+```bash
+uv tool install akashic-kb
+# or
+pipx install akashic-kb
+```
+
+The installed command is still `akashic`:
+
+```bash
+akashic --version
+```
+
+For local development:
+
+```bash
+uv sync
+uv run akashic --version
+```
+
+If installing from a checkout:
+
+```bash
+pip install .
+akashic --version
+```
+
+The documentation site commands also require Node.js and npm.
+
+## Quickstart
+
+Create a knowledge repository:
+
+```bash
+mkdir knowledge
+cd knowledge
+akashic init
+```
+
+Attach source repositories:
+
+```bash
+akashic attach /path/to/source-repo
+akashic attach /path/to/another-repo --name billing
+akashic list
+```
+
+Generate docs:
+
+```bash
+akashic generate
+```
+
+Review changes, then commit them yourself:
+
+```bash
+git status
+git add -A
+git commit -m "Generate knowledge docs"
+```
+
+Browse docs locally:
+
+```bash
+akashic serve
+```
+
+Build a static site:
+
+```bash
+akashic build-site
+```
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `akashic init [PATH]` | Initialize a knowledge repo. |
+| `akashic root` | Print discovered knowledge repo root. |
+| `akashic attach [PATH] [--name NAME]` | Register a source Git repo. |
+| `akashic detach NAME` | Remove an attached source repo. |
+| `akashic list` | List attached source repos. |
+| `akashic generate` | Compose prompts and run configured provider. |
+| `akashic serve` | Start local docs site. |
+| `akashic build-site` | Build static docs site. |
+| `akashic doctor` | Validate config, Git, repos, provider, and runtime. |
+| `akashic status` | Show attached repos, generation state, and doc counts. |
+
+Global options:
+
+- `--version`: print package version.
+- `--knowledge <dir>`: use a specific knowledge repo instead of discovering one.
+
+## Configuration
+
+Akashic stores shared repo configuration in `.akashic/config.yaml` and
+machine-local absolute paths in `.akashic/config.local.yaml`. The local config
+is gitignored so the knowledge repo can be shared across machines.
+
+Workspace discovery order:
+
+1. `--knowledge <dir>`
+2. `AKASHIC_HOME`
+3. Parent directory walk from the current working directory
+
+## Documentation
+
+Full docs live in [`docs/README.md`](docs/README.md):
+
+- [`docs/installation.md`](docs/installation.md)
+- [`docs/quickstart.md`](docs/quickstart.md)
+- [`docs/commands.md`](docs/commands.md)
+- [`docs/configuration.md`](docs/configuration.md)
+- [`docs/generation.md`](docs/generation.md)
+- [`docs/site.md`](docs/site.md)
+- [`docs/troubleshooting.md`](docs/troubleshooting.md)
+
+## Development
+
+Run tests:
+
+```bash
+uv run pytest
+```
+
+Run focused CLI commands from the checkout:
+
+```bash
+uv run akashic doctor --knowledge /path/to/knowledge
+```
+
+Frontend sources live under `frontend/` and are packaged into the Python wheel.
+
+## Current status
+
+The built-in `fake` provider writes files and is useful for exercising the full
+pipeline. Real providers (`codex`, `claude`) are documented in
+[`docs/generation.md`](docs/generation.md), including current execution
+behavior and limitations.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

akashic_kb-0.1.0/README.md

@@ -0,0 +1,169 @@
+# Akashic
+
+Akashic is a local-first CLI for Git-backed knowledge repositories. It helps
+teams keep structured Markdown documentation beside real source repositories,
+then browse that documentation through a local web UI.
+
+Akashic does not analyze code by itself. It manages the knowledge repo,
+discovers attached source repos, builds generation prompts, and hands those
+prompts to an agent provider such as Codex or Claude.
+
+## Features
+
+- Initialize a Git-backed knowledge repository.
+- Attach one or more local Git source repositories.
+- Generate structured docs for services, flows, system notes, ADRs, entities,
+  and glossary entries.
+- Preserve hand-written content through `<!-- HUMAN:START -->` sections.
+- Serve docs through a local React/Vite site.
+- Build a static read-only docs site.
+- Validate setup with `doctor` and inspect repo state with `status`.
+
+## Installation
+
+Akashic is a Python package targeting Python 3.10+.
+
+Install the released CLI:
+
+```bash
+uv tool install akashic-kb
+# or
+pipx install akashic-kb
+```
+
+The installed command is still `akashic`:
+
+```bash
+akashic --version
+```
+
+For local development:
+
+```bash
+uv sync
+uv run akashic --version
+```
+
+If installing from a checkout:
+
+```bash
+pip install .
+akashic --version
+```
+
+The documentation site commands also require Node.js and npm.
+
+## Quickstart
+
+Create a knowledge repository:
+
+```bash
+mkdir knowledge
+cd knowledge
+akashic init
+```
+
+Attach source repositories:
+
+```bash
+akashic attach /path/to/source-repo
+akashic attach /path/to/another-repo --name billing
+akashic list
+```
+
+Generate docs:
+
+```bash
+akashic generate
+```
+
+Review changes, then commit them yourself:
+
+```bash
+git status
+git add -A
+git commit -m "Generate knowledge docs"
+```
+
+Browse docs locally:
+
+```bash
+akashic serve
+```
+
+Build a static site:
+
+```bash
+akashic build-site
+```
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `akashic init [PATH]` | Initialize a knowledge repo. |
+| `akashic root` | Print discovered knowledge repo root. |
+| `akashic attach [PATH] [--name NAME]` | Register a source Git repo. |
+| `akashic detach NAME` | Remove an attached source repo. |
+| `akashic list` | List attached source repos. |
+| `akashic generate` | Compose prompts and run configured provider. |
+| `akashic serve` | Start local docs site. |
+| `akashic build-site` | Build static docs site. |
+| `akashic doctor` | Validate config, Git, repos, provider, and runtime. |
+| `akashic status` | Show attached repos, generation state, and doc counts. |
+
+Global options:
+
+- `--version`: print package version.
+- `--knowledge <dir>`: use a specific knowledge repo instead of discovering one.
+
+## Configuration
+
+Akashic stores shared repo configuration in `.akashic/config.yaml` and
+machine-local absolute paths in `.akashic/config.local.yaml`. The local config
+is gitignored so the knowledge repo can be shared across machines.
+
+Workspace discovery order:
+
+1. `--knowledge <dir>`
+2. `AKASHIC_HOME`
+3. Parent directory walk from the current working directory
+
+## Documentation
+
+Full docs live in [`docs/README.md`](docs/README.md):
+
+- [`docs/installation.md`](docs/installation.md)
+- [`docs/quickstart.md`](docs/quickstart.md)
+- [`docs/commands.md`](docs/commands.md)
+- [`docs/configuration.md`](docs/configuration.md)
+- [`docs/generation.md`](docs/generation.md)
+- [`docs/site.md`](docs/site.md)
+- [`docs/troubleshooting.md`](docs/troubleshooting.md)
+
+## Development
+
+Run tests:
+
+```bash
+uv run pytest
+```
+
+Run focused CLI commands from the checkout:
+
+```bash
+uv run akashic doctor --knowledge /path/to/knowledge
+```
+
+Frontend sources live under `frontend/` and are packaged into the Python wheel.
+
+## Current status
+
+The built-in `fake` provider writes files and is useful for exercising the full
+pipeline. Real providers (`codex`, `claude`) are documented in
+[`docs/generation.md`](docs/generation.md), including current execution
+behavior and limitations.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

akashic_kb-0.1.0/docs/README.md

@@ -0,0 +1,33 @@
+# Akashic Usage Documentation
+
+Akashic is a local-first CLI that builds a **Git-backed knowledge repository** of structured Markdown for a set of source repositories. It does not understand code itself — it composes a prompt and hands generation off to a coding agent (Claude Code or Codex).
+
+This directory documents how to install, configure, and operate the CLI as it is built today.
+
+## Documentation map
+
+| Page | Contents |
+|------|----------|
+| [installation.md](installation.md) | Requirements, install, verifying the CLI |
+| [quickstart.md](quickstart.md) | End-to-end: init → attach → generate → serve |
+| [commands.md](commands.md) | Every command, arguments, options, output |
+| [configuration.md](configuration.md) | `config.yaml`, `config.local.yaml`, every field + default |
+| [generation.md](generation.md) | Prompt system, providers, HUMAN sections, frontmatter, current limitation |
+| [site.md](site.md) | `serve` and `build-site` (MkDocs) |
+| [troubleshooting.md](troubleshooting.md) | `doctor`, common errors |
+
+## Mental model
+
+```
+akashic init      ->  scaffold a Git knowledge repo (services/ flows/ system/ adr/ entities/ glossary/)
+akashic attach    ->  register a source repo (path stored per-machine, name committed)
+akashic generate  ->  compose a master prompt + run the configured agent, which writes docs
+akashic serve     ->  browse the docs locally via MkDocs
+akashic build-site->  compile the docs to dist/
+akashic doctor    ->  validate setup
+akashic status    ->  show repos, last generation, pending changes, doc counts
+```
+
+## Current limitation (read before generating)
+
+The real agent providers (`claude`, `codex`) currently **build the invocation command but do not execute it** — live agent execution is pending verification (issue 07). Only the built-in `fake` provider actually writes files today. See [generation.md](generation.md#execution-status) for details and how to exercise the full pipeline with the fake provider.

akashic_kb-0.1.0/docs/commands.md

@@ -0,0 +1,124 @@
+# Command Reference
+
+Every command as implemented. Global options come **before** the subcommand.
+
+## Global options
+
+| Option | Description |
+|--------|-------------|
+| `--version` | Print the package version and exit. |
+| `--knowledge <dir>` | Use this directory as the knowledge repo instead of discovering one by walking up from the current directory. Resolved to an absolute path. |
+
+Workspace discovery order (for every command except `init`):
+
+1. `--knowledge <dir>` if given.
+2. `AKASHIC_HOME` environment variable if set.
+3. Walk up from the current working directory looking for `.akashic/config.yaml`.
+
+If none resolve, the command fails with: `No Akashic knowledge repo found from <dir>. Run 'akashic init' first or pass --knowledge.`
+
+---
+
+## `akashic init [PATH]`
+
+Initialize (or top up) a knowledge repository at `PATH` (default: current directory).
+
+Creates: `services/ flows/ system/ adr/ entities/ glossary/`, `.akashic/cache/`, `.akashic/logs/`, `README.md`, `.akashic/config.yaml`, `.gitignore`. Runs `git init` if not already a repo, and makes an empty initial commit if there is no `HEAD` yet.
+
+- **Idempotent:** existing directories, README, and config are left untouched; `.gitignore` lines are merged, not duplicated.
+- The initial commit is authored as `Akashic <akashic@example.invalid>` via `-c` overrides, so it does not depend on your global Git identity.
+
+`.gitignore` always contains: `.akashic/cache/`, `.akashic/logs/`, `.akashic/config.local.yaml`.
+
+Output: `Initialized Akashic repository at <root>`
+
+---
+
+## `akashic root`
+
+Print the discovered knowledge repository root. Useful for scripting and for confirming discovery works from a subdirectory.
+
+---
+
+## `akashic attach [PATH] [--name NAME]`
+
+Register a source Git repository. `PATH` defaults to the current directory.
+
+- Validates `PATH` is inside a Git work tree (`git rev-parse --is-inside-work-tree`); otherwise errors `<path> is not a Git repository.`
+- Name defaults to the resolved directory's basename; override with `--name`.
+- **Dedupe by resolved path:** re-attaching the same path updates the entry in place (and renames it if `--name` differs).
+- **Unique names:** attaching a *different* path under an already-used name errors `Repository name '<name>' is already attached.`
+- Writes the name to `config.yaml` (`repositories`) and the absolute path to `config.local.yaml`.
+
+Output: `Attached <name>`
+
+---
+
+## `akashic detach NAME`
+
+Remove a repository from both `config.yaml` and `config.local.yaml`. Deletes no files.
+
+- Unknown name errors `Repository '<name>' is not attached.`
+
+Output:
+```
+Detached <name>
+Generated docs remain; remove them with git rm when ready.
+```
+
+---
+
+## `akashic list`
+
+List attached repositories, sorted by name.
+
+- `No repositories attached.` when empty.
+- Each row is tab-separated:
+  - `<name>\t<path>` — path present and exists.
+  - `<name>\t[missing local path]` — no entry in `config.local.yaml` (e.g. after cloning the knowledge repo on a new machine).
+  - `<name>\t<path>\t[missing target]` — path recorded but the directory no longer exists.
+
+---
+
+## `akashic generate`
+
+Compose the master prompt and run the configured agent provider.
+
+Steps:
+1. Merge `config.yaml` repos with `config.local.yaml` paths. Repos with a missing/nonexistent path are **skipped with a warning**.
+2. If no valid repo remains, error `No valid attached repositories found.`
+3. Build the master prompt from bundled + custom templates (see [generation.md](generation.md)).
+4. Invoke the provider (`agent.provider`). Detect changes via `git status --porcelain` (ignoring `.akashic/`).
+5. Write `.akashic/cache/state.json` (timestamp, provider, repos, duration).
+
+- **No Git commit or staging is performed** — changes are left in the working tree.
+- Success = agent exit code 0 **and** at least one changed file. A clean exit with no changes warns: `Agent exited cleanly but produced no knowledge changes.`
+- Real providers (`claude`, `codex`) run with inherited stdio, so the interactive session takes over the terminal; Akashic waits for it to exit and reads its real exit code. See [generation.md](generation.md#execution-status).
+
+Output: warnings (to stderr), a `Changed files:` list (or `Changed files: none`), and `State written: <path>`.
+
+---
+
+## `akashic serve`
+
+Start the local React documentation site (Vite dev server) reading directly from the knowledge repo. Binds `127.0.0.1:<site.port>` (default `6969`). Blocks until the server exits (Ctrl-C). Installs frontend dependencies if missing, then runs `npm run dev`. Supports in-browser editing (Save writes back to the knowledge repo; Commit stages and commits via Git). See [site.md](site.md).
+
+Errors `… Node.js not found on PATH. …` / `… npm not found on PATH. …` if Node/npm is missing.
+
+---
+
+## `akashic build-site`
+
+Compile the docs into a static `dist/` (via the Vite build). Output: `Built site at <root>/dist`. In this static mode the site is read-only (no in-browser editing).
+
+---
+
+## `akashic doctor`
+
+Run six checks and print pass/fail for each: configuration schema, Git presence, attached repositories, agent provider, writability, and Node runtime. Exits with code `1` if any check fails. See [troubleshooting.md](troubleshooting.md).
+
+---
+
+## `akashic status`
+
+Print: attached repositories (with paths or `missing local path`), last generation (from `state.json`, or `None`), pending Git changes (porcelain), and per-section document counts (`*.md` under each section directory).

akashic_kb-0.1.0/docs/configuration.md

@@ -0,0 +1,72 @@
+# Configuration
+
+Akashic uses **two** config files under `.akashic/`:
+
+| File | Committed? | Purpose |
+|------|-----------|---------|
+| `config.yaml` | Yes | Portable settings: repo names, agent, site, generation. |
+| `config.local.yaml` | No (gitignored) | Per-machine `name → absolute path` mapping for attached repos. |
+
+This split keeps machine-specific absolute paths out of Git, so a teammate can clone the knowledge repo and set their own paths (via `akashic attach`) without breaking the committed config.
+
+Both files are validated on load with `extra="forbid"` — unknown keys raise a clear error.
+
+---
+
+## `config.yaml`
+
+Written by `init` with defaults. Full shape and defaults:
+
+```yaml
+version: 1
+
+knowledge:
+  path: "."          # knowledge root, relative to the repo; used in the prompt's layout section
+
+repositories: []      # list of { name: <str>, settings: {} }; managed by attach/detach
+
+agent:
+  provider: codex      # one of: codex | claude | fake
+  command: null        # optional path/name of the agent binary, overriding the default
+
+site:
+  port: 6969           # port used by `serve`
+
+generation:
+  model: null          # optional model hint (reserved; not yet wired into invocation)
+```
+
+### Field reference
+
+- **`version`** (int, default `1`) — config contract version.
+- **`knowledge.path`** (str, default `"."`) — knowledge root, surfaced in the prompt's Knowledge Layout section.
+- **`repositories`** (list) — each entry `{ name, settings }`. Managed by `attach`/`detach`; edit by hand only if you know what you're doing. `settings` is reserved and currently unused.
+- **`agent.provider`** (str, default `codex`) — selects the provider. `codex` and `claude` construct real agent commands (but do not execute yet — see [generation.md](generation.md#execution-status)); `fake` runs the full pipeline and writes a placeholder doc. An unknown value errors `Unknown agent provider '<x>'.`
+- **`agent.command`** (str | null) — override the binary looked up on `PATH` (default `claude` or `codex`). Useful for non-standard installs.
+- **`site.port`** (int, default `6969`) — bind port for `serve`.
+- **`generation.model`** (str | null) — reserved model hint; not yet passed to the agent.
+
+---
+
+## `config.local.yaml`
+
+Created/updated by `attach` and `detach`; gitignored. Shape:
+
+```yaml
+repositories:
+  bookings: /Users/alice/code/bookings
+  billing: /Users/alice/code/payments
+```
+
+If the file is absent, an empty mapping is assumed. A repo listed in `config.yaml` but missing here shows as `[missing local path]` in `list` and is skipped by `generate`.
+
+---
+
+## Setting up on a new machine
+
+After cloning a knowledge repo:
+
+```bash
+akashic list            # shows attached repos as [missing local path]
+akashic attach /new/machine/path/to/bookings   # re-record the local path (name preserved)
+```