Ships the fingerprints baseline fix (e7af9ae): every install since
2.7.0 had a broken Phase 7 step 2.5 that threw TypeError on the first
/understand run and left fingerprints.json empty/missing, which made
every subsequent auto-update escalate to FULL_UPDATE. This release
replaces the LLM-written script with a bundled build-fingerprints.mjs
and reorders Phase 7 to write fingerprints before meta.json.
Anyone upgrading from 2.7.0–2.7.2 should re-run /understand --full
to regenerate a valid baseline.
Ships two auto-update fixes:
- #153 (5304ff0): apply .understandignore in Phase 0 so user-excluded
paths don't inflate the structural-change count.
- #152 (dd8b724): LOAD-PATCH-SAVE template for Phase 3d fingerprints
merge, with guard against silent load failure.
Ships the fixes that landed on main after the 2.7.0 cut:
- #139 (f3ea1a3): understand-knowledge — Windows path separators in
wikilink resolution + omit empty `category` so KnowledgeMetaSchema's
`z.string().optional()` no longer drops every article node. Closes#151.
- #147 (fafb888): understand-domain — resolve $PLUGIN_ROOT at runtime
for symlink installs.
- f71bad5: understand — persist canonical edge direction during merge,
fixing the 153k auto-correction cascade. Closes#140.
Includes since 2.6.3: Hermes (#91), Cline (#116), KIMI CLI (#134)
platform support; dashboard ACCESS_TOKEN env override; README cleanup
(slogan rewrite, drop outdated overview gifs, move thanks to footer).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Remove invalid allowBuilds from pnpm-workspace.yaml (use onlyBuiltDependencies in root package.json)
- Use data-testid for search input selector (fixes / keyboard shortcut for non-English locales)
A controlled-experiment audit on a 1240-file Python project (opensre)
showed that 27.2% of resolved-internal imports never made it from
project-scanner's `importMap` into the final knowledge graph. Of the
404 source files with internal imports, 91 ended up with ZERO imports
edges in the graph despite their `file:` node being present (consistent
with main-session orchestrator dropping the entry from `batchImportData`
during batch construction), and 104 had partial coverage (consistent
with file-analyzer agent dropping rows during edge enumeration).
GitHub issue #128 reported the same failure mode at 16-21% on a Go
monorepo.
The fix has two layers:
1. `merge-batch-graphs.py` now runs a deterministic recovery pass
after merge: for every `(source, target)` in scan-result.json's
`importMap` whose source `file:` node exists in the assembled graph
and whose target `file:` node also exists, emit an `imports` edge
if the batches didn't already. Recovered edges are tagged
`recoveredFromImportMap: true` so downstream consumers can audit
which edges came from the deterministic source vs. agent emission.
The merge report logs the recovered count plus how many importMap
entries were skipped because their source/target had no graph node.
2. `file-analyzer.md` rewrites the imports edge rule to demand 1:1
emission with a self-check: "the number of `imports` edges in your
output MUST equal `sum(batchImportData[file].length)` across the
batch's code files". This drives the agent to enumerate every row
instead of summarizing — recovery should report 0 when this works.
Tests: +6 cases covering the recovery path — drops, no-double-emit,
missing source/target nodes, missing scan-result.json (incremental
update), and self-import suppression. 770 passing (was 764).
Bumps version to 2.6.3 across the five tracked manifests.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two bugs blocked /understand from running properly:
1. extract-structure.mjs:34,37 — `await import()` was called with raw
absolute paths returned by `require.resolve()` and `path.resolve()`.
On Windows those start with "C:\..." which Node 24's ESM loader
parses as URL scheme "C:" and rejects with
ERR_UNSUPPORTED_ESM_URL_SCHEME. Wrap both with `pathToFileURL().href`
so the loader receives a proper file:// URL.
2. tree-sitter native build scripts were skipped at install time
because pnpm 10 blocks postinstall scripts by default. Added the
parser packages plus esbuild and sharp to `pnpm.onlyBuiltDependencies`
so they compile during `pnpm install` and `analyzeFile` / fingerprint
generation actually work.
Without these, file-analyzer subagents fall back to direct file reads
and the importMap stays empty across all batches, which forces
assemble-reviewer to grep-recover hundreds of cross-batch edges by
hand. They also block the incremental update path entirely because
fingerprint generation crashes inside `buildFingerprintStore`.
Verified end-to-end on a 1190-file Laravel codebase: tree-sitter PHP
parses Booking.php into 18 typed functions, fingerprint baseline
builds in 1.56s, change detection correctly classifies cosmetic
vs structural diffs.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
A deep audit of the project-scanner → file-analyzer → merge pipeline
turned up a wide range of silent data-loss bugs. Each one alone is
small; together they were producing graphs with very few import edges,
missing sub-file nodes for non-code formats, and inconsistent metrics.
Root-cause fixes (high impact):
- project-scanner.md: extend import-pattern table to resolve absolute
imports for Python (`from a.b.c import x`), TS/JS (tsconfig.json
paths/baseUrl aliases), Java/Kotlin (`com.foo.Bar` ↔ file paths),
Ruby (`require 'foo/bar'` load-path), PHP (composer PSR-4 namespaces),
and C/C++ (`#include` headers). Was relative-only, which produced
empty importMap entries for the majority of real projects.
- project-scanner.md: add `.ps1`, `.bat`, `.cmd`, `.jsonc` to language
table; require non-null `language` field with an explicit fallback.
- file-analyzer.md: document `sections`, `definitions`, `services`,
`endpoints`, `steps`, `resources` in the extraction-output schema and
spell out the sub-file node-creation rules per category. Was missing,
so per-table / endpoint / resource nodes were never created from
SQL / OpenAPI / Terraform / K8s / Dockerfile parser output.
- file-analyzer.md: add explicit source-reading fallback rules for
PowerShell, Batch, Bash, Swift, Kotlin (no tree-sitter coverage).
- yaml-parser: declare `kubernetes`, `docker-compose`, `github-actions`,
`openapi` languages so files the language-registry tags with those
ids actually get section extraction. Recognize quoted top-level keys
(e.g. `"on":` in GitHub Actions). Emit one section per entry for
array-root YAML documents.
- json-parser: declare `json-schema`, `openapi`; add `stripJsoncSyntax`
helper that removes line / block comments and trailing commas before
parse so `.jsonc` files (wrangler, tsconfig with comments) parse cleanly.
- shell-parser: declare `jenkinsfile`. Tighten function-detection regex
to require a reachable `{` brace so `name() echo hi` and patterns
appearing inside heredocs are no longer false-positives.
- markdown-parser: track fenced-code-block state and skip headings
inside ``` / ~~~ blocks (`# install` shell comments were being
emitted as level-1 sections).
- merge-batch-graphs.py: add `article`, `entity`, `topic`, `claim`,
`source` to VALID_NODE_PREFIXES and TYPE_TO_PREFIX so knowledge-base
node types stop being flagged unknown / coerced to `file:`. Add
`direction` to the edge dedup key so `forward` and `bidirectional`
variants of the same (src, tgt, type) don't overwrite each other.
Use a placeholder in bare-id fallback when `filePath` is missing on
function/class nodes so unrelated `parse()` functions don't merge.
- typescript-extractor: actually compute `isDefault` for default
exports (was always emitted as `false` from buildResult).
- extract-structure.mjs: match `wc -l` semantics for `totalLines` so
the scanner's `sizeLines` and the extractor's `totalLines` agree on
POSIX text files. Filter the parser-imports fallback to relative-only
so `importCount` semantics stay *internal-import* whether the scanner
resolved them or not. Drop unused `isCode` local.
Tests: +19 cases covering JSONC parsing, markdown fenced-code skip,
YAML quoted-keys / array-root, shell function false-positives,
extract-structure import fallback semantics + totalLines off-by-one.
764 passing (was 745).
Bumps version to 2.6.2 across the five tracked manifests.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two bugs surfaced when analyzing Python projects that use absolute imports:
- The dispatch prompt (SKILL.md) and file-analyzer agent omitted the
per-file `language` field, so `extract-structure.mjs` received null and
passed it through to the graph.
- `extract-structure.mjs` used `if (importPaths)` to decide whether to
trust pre-resolved imports. Empty arrays are truthy, so files where the
project scanner could not resolve any imports (e.g. Python absolute
imports) clobbered the parser's import count with 0, never falling
back to tree-sitter's own analysis.
Bumps plugin version to 2.6.1 across the five tracked manifests and adds
unit tests for `buildResult` covering language pass-through and the
importCount fallback paths. To make the script testable, `buildResult` is
now exported and the CLI invocation is guarded so importing the module
no longer triggers `main()`.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Bumps to 2.6.0.
- MobileLayout activates via useIsMobile at <768px with bottom-tab
navigation (Graph/Info/Files); panes stay mounted (visibility
toggle) to preserve ReactFlow dimensions and FileExplorer state.
- MobileDrawer holds persona, view mode, diff, node-type filters,
layers, and tool buttons (Filter/Export/Path/Theme/Help).
- Selecting a node auto-pivots to Info; CodeViewer is always
fullscreen on mobile; SearchBar collapses to a 🔍 toggle.
- Homepage Hero/Footer/Install responsive: drop nowrap on title and
tagline, stack title spans for editorial wrap, full-width CTAs at
<480px, narrow-width spacing refinements.
- Desktop dashboard: sidebar telescopes 260/300/360px, header gaps
tighten, Path button label collapses to icon at narrow widths.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
PR #108 ships a new user-visible feature (in-dashboard source code viewer
with Files tab + double-click navigation), so it warrants a minor bump
across all 5 version-tracked files.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Bumps all five version-carrying manifests to 2.3.2, bringing
.copilot-plugin/plugin.json back in sync (was stuck at 2.2.0), and
updates CLAUDE.md to reflect the true set of files that must move
together: the nested understand-anything-plugin/.claude-plugin/plugin.json
and .copilot-plugin/plugin.json were missing, and marketplace.json was
incorrectly listed (its plugins[] entry does not support a version field).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The understand-dashboard skill now instructs agents to capture and
share the full tokenized URL from the Vite server output, so users
are not blocked by the token gate.
Bump version to 2.2.1.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Fix race condition: setGraph no longer wipes domainGraph on parallel fetch
- Remove workflow/action aliases that conflicted with pipeline type
- Remove duplicate onNodeDoubleClick handler in DomainGraphView
- Add clearActiveDomain store action (replaces direct setState call)
- Remove auto-switch to domain viewMode in setDomainGraph
- Add DomainMetaSchema Zod validation for domainMeta fields
- Add Array.isArray guards for domainMeta collections in NodeInfo
- Remove as-any cast in getDomainMeta (use typed domainMeta directly)
- Add "domain" filter category for domain/flow/step nodes
- Keep flow discriminator in step ID normalization to prevent collisions
- Update SKILL.md Phase 2 to use tool-based scanning (no missing script)
- Update EDGE_LABELS comment to reflect 29 edge types
- Bump version to 2.1.0 in all 4 required files
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Visiting localhost:5173 without ?token= now shows a clean token input
page instead of a broken dashboard. Token is persisted in sessionStorage
so refreshes work within the same browser session.
Bump version to 1.3.1.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add a --messy mode to the large graph generator so robustness cases can be
tested with null fields, aliases, dangling refs, and other malformed data.
Update the dashboard to preserve non-fatal validation issues, log
auto-corrected and dropped items, and show a warning banner with expandable
details plus copy-to-clipboard support.
- Sync .claude-plugin/plugin.json (was stuck at 1.1.0) and .cursor-plugin/plugin.json (was 1.0.5) to match main version
- Update CLAUDE.md versioning section to list all four files that must be kept in sync
- Document scripts/generate-large-graph.mjs in CLAUDE.md
Previously only FILE nodes responded to clicks with the code viewer overlay.
Now all node types open the detail viewer on click. Also added a direct click
handler on CustomNode to fix click events not firing for child nodes inside
group layers on Windows.
Bump version to 1.0.4.
Add Vite resolve aliases for core subpath exports (schema, search, types)
to fix import resolution on Windows where Node.js package exports are not
properly followed by Vite's import analysis.
Bump version to 1.0.3.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add pnpm-workspace.yaml to plugin distribution so workspace:* deps resolve on install
- Add devlop and hast-util-to-jsx-runtime as explicit dashboard dependencies (pnpm strict hoisting)
- Make tsconfig.json files self-contained to work outside monorepo root
- Add prepare script to auto-build core package after pnpm install
- Bump version to 1.0.2
- Remove ChatPanel and @anthropic-ai/sdk dependency (redundant with /understand-chat)
- Replace Monaco editor with styled summary code viewer
- New graph-first layout: 75% graph + 360px right sidebar
- Dark luxury aesthetic: deep blacks, gold/amber accents, DM Serif Display typography
- Add ProjectOverview component for sidebar default state
- Learn persona now shows tour panel directly in sidebar
- Add schema validation on graph load with error banner
- Defensive null checks in store for tour methods
- Agent pipeline: write intermediate results to disk instead of context
- Agent models: sonnet for simple tasks, opus for complex (no haiku)
- Prompt-engineer all 5 agent prompts and SKILL.md
- Auto-trigger /understand-dashboard after /understand completes
- Add dashboard screenshot to README
- Bump version to 1.0.1
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Move packages/{core,dashboard,skill} into understand-anything-plugin/ to
conform to the Claude Code plugin format. Add .claude-plugin/marketplace.json
for plugin discovery. Update workspace config and docs accordingly.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Lum1104
zhushen
Yuxiang LinandGitHub
tipichandClaude Opus 4.7