Metadata-Version: 2.4
Name: bunya-jido
Version: 0.5.0a1
Summary: Create offline semantic repository maps and bounded coding-agent context from reviewable evidence.
Author: Bunya-Jido Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/jeong87/Bunya-Jido
Project-URL: Repository, https://github.com/jeong87/Bunya-Jido
Project-URL: Issues, https://github.com/jeong87/Bunya-Jido/issues
Project-URL: Documentation, https://jeong87.github.io/Bunya-Jido/
Project-URL: Changelog, https://github.com/jeong87/Bunya-Jido/blob/main/CHANGELOG.md
Keywords: repository,semantic-map,architecture,coding-agents,static-analysis,offline-html
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tomli>=2.0.1; python_version < "3.11"
Dynamic: license-file

# Bunya-Jido

<p align="center">
  <a href="https://jeong87.github.io/Bunya-Jido/demo.html">
    <img src="docs/assets/self-map-grounded.png" alt="Grounded Bunya-Jido constellation map preview with semantic role glyphs" width="100%">
  </a>
</p>

<p align="center">
  <strong>EN</strong> | <a href="./README.ko.md">KR</a>
</p>

<p align="center">
  <a href="https://jeong87.github.io/Bunya-Jido/demo.html"><strong>Try the demo</strong></a>
</p>

<p align="center">
  <strong>A semantic repository atlas for humans and coding agents.</strong>
</p>

`Bunya-Jido` creates offline repository maps from deterministic evidence and reviewable coding-agent interpretation. It shows responsibilities, workflows, and change boundaries for humans, then derives bounded task-oriented navigation context for coding agents.

The project is inspired by Cheonsang Yeolcha Bunyajido, the Korean star map that reads the sky through regions and relationships. In the same spirit, Bunya-Jido gathers files, modules, docs, configuration, runtime artifacts, and coding-agent interpretation into one map of a codebase.

The goal is a grounded semantic map whose important claims can be inspected, not an automatic claim of architectural truth.

## Benchmark Snapshot

Recent synchronized synthetic benchmarks suggest that Bunya-Jido can reduce
large-repository repair cost while preserving bugfix success:

| Synthetic repo | Bugfix success | Token change | Time change |
| --- | ---: | ---: | ---: |
| 28.7K SLOC | 24/24 -> 24/24 | -18.8% | -28.0% |
| 126.7K SLOC | 39/39 -> 39/39 | -22.8% | -12.5% |

Synthetic benchmark; GPT-5.5 Medium; 3 repetitions per scenario. Results do
not prove equivalent gains on production repositories. See
[docs/BENCHMARKS.md](docs/BENCHMARKS.md) for methodology, limitations, and
links to the detailed reports.

## Quick Start

1. In the repository you want to map, install the public alpha from PyPI:

```bash
python -m pip install --pre bunya-jido
bunya-jido --version
```

The `--pre` flag is required while the newest release is an alpha. If your
environment has an older `pip`, run `python -m pip install --upgrade pip`
first.

2. From that repository root, give your coding agent(gpt5.5-xhigh is recommended) this prompt:

```text
Run `bunya-jido prepare --root . --atlas-mode studio --quiet`, then read and execute `.bunya-jido/BUNYA_JIDO_BLUEPRINT_PROMPT.md`. Use `.bunya-jido/ATLAS_INTERVIEW.md` as an internal checklist while creating or refreshing `.bunya-jido/COMPONENTS.md`, `.bunya-jido/WORKFLOWS.md`, `.bunya-jido/REPOSITORY_THESIS.md`, `.bunya-jido/PROJECTIONS.md`, `.bunya-jido/SCENARIOS.md`, `.bunya-jido/bunya-jido.blueprint.json`, and `.bunya-jido/bunya-jido.agent-map.json`; run `bunya-jido validate-blueprint --root .`, `bunya-jido validate-agent-map --root .`, and `bunya-jido evaluate-atlas-quality --root . --require-pass --json`; fix errors and grounding blockers; then run `bunya-jido build --root . --out bunya-jido.html`; confirm the HTML path and say `ready`.
```

Open `bunya-jido.html` in your browser.

## What It Creates

Bunya-Jido creates two outputs.

1. A single HTML architecture map that opens directly in a browser.
2. A `.bunya-jido/` context pack that coding agents such as Codex, Claude Code, Cursor, and Cline can use as bounded handoff context for a task.

The HTML map works offline. It does not need a server, database, internet connection, or JavaScript build step.

## Why It Exists

Static analysis tools can tell that `foo.py` imports `bar.py`. They usually cannot tell which module owns control flow, which file is a runtime adapter, or which document is the contract to read before changing behavior.

Bunya-Jido fills that gap with a coding agent.

It first scans the repository to collect raw evidence. Then a coding agent reads the repository and writes component and workflow documents. Bunya-Jido validates those outputs and renders an interactive HTML map with evidence paths attached.

Bunya-Jido focuses on questions like these:

- What are the main responsibility areas in this repository?
- In what order do the important workflows move?
- Which files, docs, and tests should be read before changing a feature?
- Which boundaries should a coding agent avoid touching casually?
- What real evidence supports each graph node and edge?

## Two Map Modes

Bunya-Jido can produce two related, but different, map forms.

### Deterministic Scan Map

Without a semantic blueprint, Bunya-Jido renders repository structure and detected hints gathered from source files, documentation, configuration, and selected artifacts. This is useful discovery evidence, not an architectural judgment.

```bash
bunya-jido build --root . --blueprint none --out bunya-jido.html
```

### Semantic Blueprint Map

When `.bunya-jido/bunya-jido.blueprint.json` exists, Bunya-Jido renders an evidence-linked architectural interpretation written with a coding agent and checked by the tool. This is the recommended mode for responsibility areas, workflows, and agent handoff context.

Semantic maps with unresolved core grounding blockers are not built by default. To inspect a structurally valid but unfinished map explicitly as a draft, use:

```bash
bunya-jido build --root . --allow-draft --out bunya-jido.html
```

## Installation And Mode Details

Requirements:

- Python 3.10 or newer with `pip`.
- Git for the current GitHub installation command.
- For Blueprint Mode, a coding agent that can read and write the repository
  and run terminal commands, such as Codex or Claude Code.
- A browser only when you want to inspect the generated offline HTML map.

The CLI is designed for Windows, macOS, and Linux. CI tests Ubuntu with Python
3.10-3.12 and Windows and macOS with Python 3.12.

Install the public alpha from PyPI with one command:

```bash
python -m pip install --pre bunya-jido
```

The `--pre` flag selects alpha releases such as `0.5.0a1`. When Bunya-Jido has
a stable release, `python -m pip install bunya-jido` will be enough. To test
unreleased `main`, install directly from GitHub:

```bash
python -m pip install git+https://github.com/jeong87/Bunya-Jido.git
```

Check the command:

```bash
bunya-jido --version
```

### Install By Operating System

Windows PowerShell:

```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --pre bunya-jido
bunya-jido --version
```

macOS or Linux (`bash` / `zsh`):

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --pre bunya-jido
bunya-jido --version
```

Any Python version from 3.10 onward is acceptable; `3.12` is shown in the
Windows example because it is also exercised in all three CI operating
systems.

### Blueprint Mode

Blueprint mode is the base semantic workflow. The Quick Start above selects
its richer Studio atlas extension; use this baseline path when authored
projections and narrated scenarios are not needed.

1. Bunya-Jido scans the repository deterministically.
2. A coding agent reads the repository and scan output.
3. The agent writes component docs, workflow docs, a blueprint, and an agent map.
4. Bunya-Jido validates those files.
5. The validated blueprint is rendered into a single HTML map.

From the repository root, ask your coding agent:

```text
Run `bunya-jido prepare --root . --quiet` if needed, then read and execute `.bunya-jido/BUNYA_JIDO_BLUEPRINT_PROMPT.md`. Create or refresh `.bunya-jido/COMPONENTS.md`, `.bunya-jido/WORKFLOWS.md`, `.bunya-jido/bunya-jido.blueprint.json`, and `.bunya-jido/bunya-jido.agent-map.json`; run `bunya-jido validate-blueprint --root .` and `bunya-jido validate-agent-map --root .`; fix errors and grounding blockers, and reduce classification warnings when practical; then run `bunya-jido build --root . --out bunya-jido.html`; confirm the HTML path and say `ready`.
```

This prompt builds `bunya-jido.html` at the end. If you edit the blueprint and want to rebuild the map yourself, run:

```bash
bunya-jido build --root . --out bunya-jido.html
```

Open `bunya-jido.html` in your browser.

#### Studio Atlas Mode

The recommended Quick Start above uses Studio mode. It asks a coding agent to
compare repository-specific explanations before publishing a narrated atlas:

```bash
bunya-jido prepare --root . --atlas-mode studio --quiet
```

Studio preparation additionally creates `ATLAS_INTERVIEW.md`,
`REPOSITORY_THESIS.md`, `PROJECTIONS.md`, and `SCENARIOS.md`. The interview is
an internal checklist; the authored documents ask the coding agent, in
role-based passes, to select a primary projection and an honest scenario
policy: `required`, `optional`, or `none_with_reason`. Newly authored Studio
blueprints also record optional `atlas.decision_record` metadata so the chosen
projection, considered alternatives, and centrality risks remain reviewable;
older v2 artifacts without it remain compatible. Studio preparation generates the additive
`bunya-jido-blueprint-v2` schema, and `validate-blueprint`, `build`, and
`diagnose` accept its vocabulary, projection, and scenario contract. The
offline viewer now renders map-local node/relation families, starts on the
primary projection, offers projection presets, and reveals authored
contextual neighbors on selection. When a validated Studio atlas publishes
scenarios, the viewer provides narrated playback with an explicit evidence
basis badge: behavioral paths can animate a token, while structural tours use
step highlighting without implying runtime order. Exiting playback restores
the previous view and filters. Classic mode and `none_with_reason` atlases
show no scenario launcher. A validated task route can optionally carry one
Studio projection and related scenarios as bounded reading context; the
viewer exposes related trusted routes on selected nodes and can copy that
coding-agent context directly.

For a Studio v2 blueprint, evaluate measurable first-read and scenario-policy
signals with:

```bash
bunya-jido evaluate-atlas-quality --root . --require-pass --json
```

This quality gate blocks deterministic contract failures and reports
readability heuristics such as dense overview graphs or weak core inspection.
It also reports review-required narration signals when a structural tour
sounds like runtime execution, playback copy is too thin or too burdensome,
or a scenario misses the selected projection's landmarks. Projection choice
and narration meaning remain explicitly review-required judgments rather than
automated proof; review-only findings do not change `status: "passed"` or
`--require-pass`. For an optional maintainer-readable summary:

```bash
bunya-jido evaluate-atlas-quality --root . --require-pass --write-report
```

This writes `.bunya-jido/ATLAS_QUALITY_REPORT.md` in the local workspace.

This repository's committed self-map now uses Studio v2: its primary
projection is `Trusted Publication`, it preserves a machine-readable editorial
decision record, and it publishes two evidence-badged behavioral scenarios. To guard against a tool shaped only for its own source
tree, the Studio benchmark renders and validates six distinct repository
shapes, including workflow systems, web applications, SDKs, transformation
pipelines, and utilities with no invented runtime scenario. See
[docs/STUDIO_BENCHMARK.md](docs/STUDIO_BENCHMARK.md) and
[docs/gallery.md](docs/gallery.md). The published gallery includes this
self-map, a provenance-focused coverage fixture, and evidence-backed SDK,
web-state, compiler, and utility miniatures. Together they show structural
tours, grounded behavioral playback, and honest `none_with_reason` output
without forcing every repository into one lifecycle.

## Generated Files

`bunya-jido prepare` creates these files:

```text
.bunya-jido/
  COMPONENTS.md
  WORKFLOWS.md
  bunya-jido.blueprint.json
  bunya-jido.agent-map.json
  bunya-jido-static-scan.json
  bunya-jido-blueprint.schema.json
  bunya-jido-agent-map.schema.json
  BUNYA_JIDO_BLUEPRINT_PROMPT.md
  CODEX_ONE_LINER.txt
```

A mapped repository can additionally track `.bunya-jido/MAP_REVIEW.md` to
record a reviewed no-structure-change decision for `check-stale`.
With `--atlas-mode studio`, preparation also creates `ATLAS_INTERVIEW.md` as
an internal checklist plus `REPOSITORY_THESIS.md`, `PROJECTIONS.md`, and
`SCENARIOS.md`, and emits the Studio v2 blueprint schema. Running
`evaluate-atlas-quality --write-report` additionally writes the optional local
`ATLAS_QUALITY_REPORT.md` review summary.

### `COMPONENTS.md`

A responsibility-oriented document for the repository's main components.

Each component should include its role, evidence files, inputs, outputs, contracts, related tests, and the places a coding agent should read first. The point is not to mirror folder names, but to reveal real responsibilities and change boundaries.

### `WORKFLOWS.md`

A document that explains the repository's main flows in order.

For example, it can describe how a CLI entrypoint moves through scanning, blueprint validation, rendering, and HTML output. It should also leave a path for future feature work or debugging.

### `bunya-jido.blueprint.json`

The machine-readable graph used by the HTML map.

It contains nodes, edges, planes, groups, detail nodes, and evidence. Because it is derived from `COMPONENTS.md` and `WORKFLOWS.md`, it should be smaller and more semantic than a raw dependency graph.

Validate it with:

```bash
bunya-jido validate-blueprint --root .
```

### `bunya-jido.agent-map.json`

A task map for coding agents.

For tasks such as "modify provider behavior," "change the storage layer," or "debug runtime failure," it records what to read first, which tests matter, what is safe to edit, and which boundaries need care.

Its task routes must resolve against the semantic blueprint and repository-relative required reading and tests before they can be emitted as trusted agent context or shown as map paths. In Studio maps, routes may additionally reference validated `projection_context` and `scenario_context` IDs to carry a bounded reading orientation.

Validate it with:

```bash
bunya-jido validate-agent-map --root .
```

### `bunya-jido-static-scan.json`

A deterministic scan result produced without an LLM.

It includes files, modules, imports, docs, configuration, runtime artifacts, and external API hints. Provider hint evidence carries origin/type metadata, and token examples inside generated prompts, schemas, or viewer templates are not promoted as Studio overlay nodes. The coding agent uses the remaining observations as raw evidence while writing the blueprint.

## Diagnostics

Use diagnostics to report which artifact mode is present and whether a semantic
map is actually eligible for grounded publication:

```bash
bunya-jido diagnose --root .
bunya-jido diagnose --root . --require-grounded --json
bunya-jido evaluate-atlas-quality --root . --require-pass --json  # Studio v2
bunya-jido evaluate-atlas-quality --root . --require-pass --write-report  # optional review summary
```

`--require-grounded` exits unsuccessfully for a static scan or a blocked
semantic blueprint. Release automation uses this exact gate rather than
assuming a generated map is trusted.
`evaluate-atlas-quality` applies to Studio v2 blueprints, keeps measurable
warnings separate from editorial review, and emits additive
`review_required`/warning-count fields for automation that wants to surface
human follow-up without blocking publication.

## HTML Map

The generated HTML map includes:

- a canvas-first constellation overview with semantic role glyphs and a workflow launcher bar
- a compact repository summary with a guided-tour entry and keyboard-accessible repository outline
- responsibility-oriented plane clusters
- authored plane-purpose glossary plus viewer-facing node and relation families
- Studio v2 map-local glyph/line vocabularies, primary projection tabs, and contextual direct-neighbor reveal
- Studio v2 narrated scenario playback with basis badges, pause/step/speed controls, and exit restoration
- semantic inspector cards for authored purpose, inputs, outputs, and constraints
- subtle direction arrows and numbered workflow landmarks without changing the constellation layout
- related trusted task routes on selected nodes with a copyable coding-agent context action
- node-family, relation-family, and confidence filtering
- local graph focus around a selected node
- a trust panel showing `Static Scan`, `Grounded`, or explicit `Draft` status
- an evidence panel showing source paths, relation confidence, and recorded evidence
- explicit `Overview`, `Inspect Evidence`, and `Implementation Detail` exploration modes
- labeled path presets for blueprint views, workflows, and validated agent-map task routes
- PNG and JSON export
- implementation-detail expansion when the blueprint provides detail nodes
- horizontally navigable compact controls and drawer-based outline access on narrow screens

The map is not the source of truth. The evidence remains in the repository's code, docs, configuration, tests, runtime artifacts, and validated blueprint files. Bunya-Jido projects that evidence into a form that is easier to inspect.

Validated agent-map task routes now appear both in generated context output and as `Task Route` path presets in the HTML map. Routes may expose validated Studio projection/scenario context and start-node responsibility in both the CLI handoff and the viewer copy action. Missing blueprint nodes, workflows, required reading, tests, or declared Studio context references block trusted context and normal semantic publication.

## Working With Coding Agents

Once a blueprint and agent map exist, Bunya-Jido can generate a focused handoff for a task.

```bash
bunya-jido context --root . --task "modify provider behavior" --out .bunya-jido/CONTEXT.md
```

When a request matches a validated task route, the generated context identifies
why it matched and supplies that route's reading, contract, and test guidance.
If the route declares validated Studio reading context, it also identifies the
relevant projection question, qualified scenarios, and starting responsibility.
If no route matches, it states `No matching trusted route` instead of
presenting an unrelated prepared path as guidance. An `IN_SCOPE_NO_ROUTE`
repair may additionally receive capped, evidence-backed read-only discovery
with likely areas, first reads, tests, search commands, and node/workflow
commands for requesting a new decision.

Context selection is decision-aware:

| Decision | Meaning | Edit policy | Execution policy |
|---|---|---|---|
| `MATCH` | One trusted route has sufficient evidence and separation | `workspace_write` | `workspace_write` |
| `IN_SCOPE_NO_ROUTE` | The request is repository-related, but the map has no sufficient route | `cautious` | `read_only_discovery` |
| `OUT_OF_SCOPE` | The request conflicts with a reviewed repository boundary | `read_only` | `read_only` |
| `UNCERTAIN` | Scope or route sufficiency cannot be established safely | `read_only` | `read_only` |

Agent maps may declare optional repository scope and route-level negative
boundaries. Matching uses exact meaningful terms, explicit route-use phrases,
common failure modes, route-specific grounded node/workflow evidence, and
conservative route separation. A failure mode or shared-workflow term cannot
confirm a route alone; non-`MATCH` decisions never expose trusted routes or
safe-edit paths.

Machine-readable decisions are available for integrations:

```bash
bunya-jido context --root . --task "modify provider behavior" --json
```

The JSON report includes `execution_policy`, `agent_instruction`, and an
optional `discovery_context` only for grounded `IN_SCOPE_NO_ROUTE` discovery.
Integrations should enforce `read_only` or `read_only_discovery` before
launching an agent; Bunya-Jido reports the policy but does not control another
process's sandbox. See
[docs/CONTEXT_EXECUTION_POLICY.md](docs/CONTEXT_EXECUTION_POLICY.md).

Task-selected Markdown and JSON context is compact by default: it keeps the
selected route or bounded discovery contract while removing repeated
diagnostics and unrelated generated-document references. Use `--verbose`
when debugging route scores or inspecting full discovery evidence.

You can also focus on a specific node:

```bash
bunya-jido context --root . --node component:llm_router --out .bunya-jido/CONTEXT.md
```

Or refresh context from changed files:

```bash
bunya-jido refresh-context --root . \
  --changed-file src/foo.py \
  --changed-file tests/test_foo.py \
  --out .bunya-jido/REFRESH_CONTEXT.md
```

`refresh-context` recommends only routes justified by the supplied changed
files: route reading/test/edit paths or grounded evidence for a route start
node. Its output explains each file match; unrelated changes produce
`No matching trusted route`.

### Keeping The Map Current

Bunya-Jido does not silently rewrite a semantic map whenever source code
changes. A coding agent still reviews and authors semantic updates. To make
that maintenance easy to notice, a mapped repository can define
`stale_map_policy` in `.bunya-jido/bunya-jido.agent-map.json` and run:

```bash
bunya-jido check-stale --root . --git-diff --require-reviewed
```

For a branch compared with its base, pass a revision range:

```bash
bunya-jido check-stale --root . --git-diff origin/main...HEAD --require-reviewed
```

If policy-covered files changed without an updated blueprint, agent map, or
`.bunya-jido/MAP_REVIEW.md` note, the command reports `stale` and fails in
strict mode. Refresh with the Blueprint Mode prompt when the architecture
changed; when it did not, record the reviewed decision in `MAP_REVIEW.md`.
Either form reports `review_recorded`; it records review work but does not
automatically prove the authored architecture complete. CI can run the same
gate on each pull request or push. Local `--git-diff` reads tracked changes;
pass new untracked files explicitly with `--changed-file`.

### Evaluating Agent Utility

A mapped repository can commit bounded context acceptance cases in
`.bunya-jido/bunya-jido.agent-evaluation.json` and run:

```bash
bunya-jido evaluate-agent-utility --root . --require-pass --json
```

The suite checks expected first reads, test recall, contract/edit boundaries,
honest no-match handling, normal-bugfix route/discovery recovery, and
change-aware refresh output. It reports trusted-route recall, bounded-discovery
coverage, actionable-guidance coverage, and normal-bugfix hard-rejection rate. It is a
deterministic check of the generated handoff, not proof that a live coding
agent read or obeyed it. The evaluation format and an optional live-agent
observation protocol are documented in
[docs/AGENT_UTILITY_EVALUATION.md](docs/AGENT_UTILITY_EVALUATION.md).
The report also estimates compact versus verbose context-output size; this is
not a substitute for measured live-agent task tokens.

### Auditing Live-Agent Benchmark Changes

Live-agent benchmark runners can reject dirty baselines and observe tracked,
staged, deleted, renamed, untracked, and Codex JSONL-reported write activity:

```bash
bunya-jido audit-worktree --root workspace --require-clean --json
bunya-jido audit-worktree --root workspace --jsonl task.codex.jsonl --allow-artifact "results/**" --require-jsonl --json
```

The audit keeps final workspace changes separate from write-then-revert
attempts. It also classifies common generated/cache noise such as Python
bytecode caches, test caches, coverage output, and OS/editor temp files so
no-match production-edit checks are not polluted by environment artifacts.
Runner-owned outputs still need explicit `--allow-artifact` globs. See
[docs/BENCHMARK_RESULT_CONTRACT.md](docs/BENCHMARK_RESULT_CONTRACT.md) for the
runner integration and result contract.

After collecting compatible live results, compare only paired
safe-and-resolved tasks:

```bash
bunya-jido summarize-token-efficiency \
  --results results/token-runs.json \
  --baseline no-map \
  --candidate 0.5-map \
  --require-comparable \
  --json
```

The summary separates context output, repair, no-match, map-authoring, and
safe-and-resolved task tokens, and reports medians and break-even task counts.

Measure resolution time with the same safety filter and explicit repeated-run
pairing:

```bash
bunya-jido summarize-time-efficiency \
  --results results/time-runs.json \
  --baseline no-map \
  --candidate 0.5-map \
  --require-comparable \
  --json
```

The time summary reports cumulative, median, nearest-rank p90,
context-generation, discovery-to-first-edit, total-resolution, per-task, and
optional authoring-time break-even measures. It is reporting-only and does not
tune routing behavior from benchmark scenarios.

These files are meant to be pasted or attached before handing work to a coding agent.

## Alpha Limitations

Bunya-Jido is public-alpha software. The most important current limits are:

- Python repositories are the strongest supported target today.
- Semantic map authoring requires a capable coding agent and a meaningful
  initial token budget.
- Small repositories may not recover the authoring cost.
- A trusted route can still point to a downstream compensation path rather
  than the root-cause owner; review the evidence before editing.
- `IN_SCOPE_NO_ROUTE` two-stage discovery depends on the integration honoring
  the read-only discovery contract before editing.
- Synthetic benchmark results do not prove equivalent production-repository
  gains.

## Supported Scope

The current strongest fit is Python repositories with nontrivial workflows, especially developer tooling, research, automation, and agent-oriented projects.

- Python module/import and symbol scanning is the primary code-scanning surface today.
- Markdown documentation, common package/config files, selected runtime/data artifacts, and provenance-tagged provider/API hints are used as discovery evidence; generated prompt/schema/template examples are filtered from Studio overlays.
- JavaScript and TypeScript files are scanned on a limited basis, but local module-resolution coverage is still developing.

Bunya-Jido does not yet claim equivalent semantic coverage across languages or automatic proof that an authored architecture map is correct.

See the [scanner coverage matrix](docs/SCANNER_COVERAGE.md) for exact current behavior, representative fixtures, JS/TS local-resolution limits, and the evidence required before adding a new support claim.

## Agent Activation

Bunya-Jido can activate task-context instructions for Codex, Claude Code,
Cursor, and Cline so an agent checks the validated map before implementation,
debugging, or review work.

```bash
bunya-jido install-agent-guides --root . --agent all --activate --dry-run
bunya-jido install-agent-guides --root . --agent all --activate
```

Native activation targets:

```text
Codex       AGENTS.md
Claude Code CLAUDE.md
Cursor      .cursor/rules/bunya-jido.mdc
Cline       .clinerules/bunya-jido.md
```

Activation inserts or updates only a marked Bunya-Jido block, preserving any
existing project instructions. The block tells the agent to run `bunya-jido
context --root . --task "<user request>"`, use matched reading/contracts/tests,
keep `OUT_OF_SCOPE` and `UNCERTAIN` decisions read-only, keep initial
`IN_SCOPE_NO_ROUTE` discovery read-only without invented guidance, rerun
context with a justified node/workflow focus before editing, and run `refresh-context`
from actual changed files after editing. If a repository
defines a stale-map policy, it also tells the agent to run `check-stale` and
either update the map or record an explicit no-structure-change review.

To temporarily force a no-map run without editing these instruction files, set
`BUNYA_JIDO_CONTEXT=off` or `BUNYA_JIDO_DISABLE_CONTEXT=1` before invoking
`bunya-jido context` or `refresh-context`. The command then returns
`decision=DISABLED`, no trusted routes, no safe-edit paths, and a read-only
sandbox recommendation.

To persistently turn off native activation, remove only the managed
Bunya-Jido block:

```bash
bunya-jido install-agent-guides --root . --agent all --deactivate --dry-run
bunya-jido install-agent-guides --root . --agent all --deactivate
```

Deactivation preserves any project instructions outside the marked block. If a
native instruction file was created only for Bunya-Jido activation and has no
other content, it is removed. This does not delete `.bunya-jido/` map artifacts
or the generated HTML map.

To generate copyable snippets without touching native project instruction
files, omit `--activate`:

```bash
bunya-jido install-agent-guides --root . --agent all
```

Those snippets are written under `.bunya-jido/agent-guides/`.

## Data-Heavy Repositories

By default, Bunya-Jido summarizes dataset-like directories as directory-level nodes. It does not turn thousands of data files into individual nodes.

```bash
bunya-jido build --root . --data-policy summary --out bunya-jido.html
```

Other options:

```bash
bunya-jido build --root . --data-policy sample --max-data-files 50 --out bunya-jido.html
bunya-jido build --root . --data-policy full --out bunya-jido.html
```

Use `summary` for most repositories. Use `sample` when the shape of a data directory matters, and `full` only for small example datasets or small artifact folders.

## Design Principles

- Prefer a small semantic architecture map over a giant raw dependency graph.
- Attach evidence paths to nodes and edges whenever possible.
- Let an LLM help author the blueprint, but let Bunya-Jido validate and render deterministically.
- Keep the final map openable offline.
- Treat the map as an inspectable projection, not the territory itself.

## Limitations

- Blueprint quality depends on the coding agent's analysis quality.
- Static scanning is fast, but it can become noisy on large repositories.
- Bunya-Jido does not call an LLM by itself.
- The HTML map does not prove architectural correctness. It makes assumptions and evidence easier to inspect.

## Release And Roadmap

The original grounded-map implementation roadmap is complete through PR8.
PR9 through PR12 extend agent consumption with honest route matching, optional
native agent activation, change-aware refresh routing, stale-map review, and
bounded utility evaluation. The Studio Atlas phases add repository-specific
projections, truthful scenario playback, deterministic quality checks, and a
cross-domain benchmark; the committed self-map is now its Studio v2 example.
See
[docs/gallery.md](docs/gallery.md) for the committed Grounded self-map,
[docs/RELEASING.md](docs/RELEASING.md) for public-alpha release gates and
publishing setup, [CHANGELOG.md](CHANGELOG.md) for release notes, and
[CONTRIBUTING.md](CONTRIBUTING.md) for contribution requirements. The completed
and extended implementation plan remains recorded in
[docs/CONTRIBUTION_PLAN.md](docs/CONTRIBUTION_PLAN.md). The follow-up
constellation-viewer design pass is reflected in the live demo and preview
image above.

## License

MIT.
