Understand-Anything

docs: note local-model option and token-usage expectations in install steps

Lum1104 · 2026-06-19 11:37:46 +08:00

7f5a717694

chore: bump version 2.7.7 → 2.8.0 for Dart language support

thejesh · 2026-06-13 05:57:24 -07:00

6be6ad057c

feat(install): add Nanobot platform support

chengyongru · 2026-06-09 16:52:35 +08:00

8de0b3b11d

feat(understand): auto-detect conversation language on first run

When /understand runs with no --language flag and no stored outputLanguage,
step 3.6 now infers the conversation language and — only when it is non-English
— confirms once before generating, then persists the choice to config.json.
English conversations keep the exact same silent `en` path; --language flag and
stored config still take priority. README documents the behavior; version
bumped 2.7.5 -> 2.7.6 across all five manifests (user-visible behavior change).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Bozheng Long · 2026-06-03 21:19:52 +08:00

92e76190aa

Merge pull request #204 from Lum1104/feat/semantic-batching-and-output-chunking

fix(#159): semantic batching + bundled importMap + Phase 1 speedup

Yuxiang Lin · 2026-05-24 20:12:14 +08:00

a59a573a1d

chore(release): bump version to 2.7.4

Lum1104 · 2026-05-21 19:36:17 +08:00

d14d6f8f96

chore(release): bump version to 2.7.3

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.

Lum1104 · 2026-05-18 10:13:22 +08:00

0e39f227a4

chore(release): bump version to 2.7.2

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.

Lum1104 · 2026-05-18 09:59:05 +08:00

97fa2f3cab

chore(release): bump version to 2.7.1

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.

Lum1104 · 2026-05-18 09:48:44 +08:00

2da74848e5

chore(release): bump version to 2.7.0

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>

Lum1104 · 2026-05-12 14:27:12 +08:00

04c84ab4a4

fix: Address code review feedback for PR #142

- 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)

zhushen · 2026-05-12 11:02:13 +08:00

2083342199

Merge pull request #124 from tipich/fix/windows-pnpm10-compat

fix(skill): make /understand work on Windows + pnpm 10

Yuxiang Lin · 2026-05-10 09:38:18 +08:00

a381c41ef6

fix(merge): recover imports edges file-analyzer batches drop

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>

Lum1104 · 2026-05-08 19:35:34 +08:00

05fd42343c

fix(skill): make /understand work on Windows + pnpm 10

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>

tipich · 2026-05-08 13:48:36 +03:00

366368face

fix(pipeline): close 12 sources of silent data loss in graph extraction

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>

Lum1104 · 2026-05-07 21:44:24 +08:00

c49c46d974

fix(file-analyzer): preserve language and fall back when imports unresolved

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>

Lum1104 · 2026-05-07 21:02:47 +08:00

7834f9bc75

feat(dashboard): add mobile layout and responsive fixes

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>

Lum1104 · 2026-05-05 16:25:56 +08:00

880e223bb4

chore: bump to 2.5.1

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Lum1104 · 2026-05-04 19:24:15 +08:00

4e1b83a35d

chore: bump to 2.5.0

ELK + lazy container architecture (PR #111) lands as a new minor.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Lum1104 · 2026-05-03 18:16:02 +08:00

2320ac9103

chore: bump version to 2.4.0

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>

Lum1104 · 2026-05-01 17:57:43 +08:00

87e3150c4b

chore: bump to 2.3.2 and sync version manifest list

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>

Lum1104 · 2026-04-24 12:13:58 +08:00

bdba4795e2

chore: bump version to 2.3.1

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Lum1104 · 2026-04-12 15:23:50 +08:00

ca5e3b8e21

fix: include access token in dashboard URL reported to user

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>

Lum1104 · 2026-04-09 22:50:20 +08:00

1842541a93

fix: address PR #71 review findings and bump version to 2.2.0

Fix all actionable code review items: add missing domain/flow/step node
types, fix batch numeric sorting, align gate thresholds, merge duplicate
tour steps instead of dropping, add Writing Results section to
assemble-reviewer, use skill-relative script paths, and add func→function
type mapping.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Lum1104 · 2026-04-04 12:28:20 +08:00

52050e40cb

fix: address all code review issues from both reviewers

- 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>

Lum1104 · 2026-04-02 14:52:34 +08:00

7d3c049422

chore: bump version to 2.0.0

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-28 23:30:34 +08:00

41d72e32f1

chore: bump version to 1.4.0 for universal file type support

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Lum1104 · 2026-03-28 19:15:53 +08:00

49bcfd604c

feat(dashboard): add token gate page for unauthenticated access

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>

Lum1104 · 2026-03-28 16:59:51 +08:00

26cc41cf03

chore: bump version to 1.3.0

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-28 16:45:05 +08:00

86be2da691

chore: bump version to 1.2.2

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Lum1104 · 2026-03-27 17:09:04 +08:00

a33240180d

feat(dashboard): surface graph validation issues and add messy graph fixtures

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.

Lum1104 · 2026-03-26 20:44:07 +08:00

835377b968

chore: bump version to 1.2.0 and sync all plugin manifests

- 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

Lum1104 · 2026-03-24 20:26:31 +08:00

d697aefa53

chore: bump version to 1.1.1

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-21 23:08:56 +08:00

8134bb95ca

docs: add star history and bump version to 1.1.0

Lum1104 · 2026-03-19 23:48:26 +08:00

54259f3b86

chore: bump version to 1.0.5

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Lum1104 · 2026-03-17 11:10:14 +08:00

b9b48466c3

fix(dashboard): enable click and expand for all node types (function, class, etc.)

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.

Lum1104 · 2026-03-16 14:34:11 +08:00

b82efea88e

fix: resolve plugin installation failures for workspace resolution and missing dependencies

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>

Lum1104 · 2026-03-16 12:23:48 +08:00

5c0afb35ff

fix: resolve plugin installation failures for workspace resolution and missing dependencies

- 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

Lum1104 · 2026-03-15 19:12:55 +08:00

bdf6cf6856

feat: redesign dashboard with dark luxury theme, improve agent pipeline

- 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>

Lum1104 · 2026-03-15 12:36:39 +08:00

343e94c9a7

refactor: restructure monorepo into Claude Code plugin layout

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 · 2026-03-15 11:16:43 +08:00

b75235919e

40 Commits