Understand-Anything

Merge pull request #208 from evanclan/docs/cursor-manual-install-i18n

docs(readme): add Cursor manual install fallback to 7 translated READMEs

Yuxiang Lin · 2026-05-26 08:03:39 +08:00

1a16e4de61

Merge pull request #231 from atlas-architect/fix/scan-project-non-ascii-paths

fix(scan-project): preserve non-ASCII path bytes via `git ls-files -z`

Yuxiang Lin · 2026-05-26 08:02:54 +08:00

44d1d59028

fix(scan-project): preserve non-ASCII path bytes via git ls-files -z

`enumerateViaGit` ran `git ls-files -co --exclude-standard` (newline-separated
output) and then `split('\n').map(trim)` on the result. Without `-z`,
`git ls-files` C-escapes any byte outside the locale's "safe" set and wraps
the path in double quotes — for example, a directory named `30. 🏗️ docs/`
comes back as `"30. \360\237\217\227\357\270\217 docs/"`. Downstream
consumers then can't round-trip those octal-quoted strings to real disk
paths, so every file under such directories is silently dropped from the
scan.

This is particularly biting on Windows (where the issue surfaces even with
UTF-8 locale settings) and for any project that uses emoji, accented
characters, or CJK codepoints in directory names — which is increasingly
common in design/spec/journal trees.

The fix is to use `-z` (NUL-terminated output), the same approach git
itself documents for downstream consumers (e.g. `xargs -0`). NUL-separated
chunks are raw bytes, so every codepoint round-trips back to its real disk
path on every platform. Split on `\0` instead of `\n`; drop the now-
unnecessary `.trim()`.

Verified on a real project with emoji-prefixed directory names:

  bare `git ls-files`:
    "30. \360\237\217\227\357\270\217\360\237\247\231\342\200\215..."

  `git ls-files -z`:
    30. 🏗️🧙‍♂️🔮 BD-CCSP/01. Demo's/DEMO--...

Discovered during a multi-agent scan of an Atlas Intelligence spoke repo;
~33 design-intent files in `30. 🏗️ BD-{app}/` directories were silently
dropped per scan. Full report: atlas-intelligence-io/fleet-feedback#491.

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

Adam Herring · 2026-05-25 11:09:20 -07:00

b4d856d3b8

docs(readme): add Cursor manual install fallback to 7 translated READMEs (#172 )

PR #199 documented the community-reported Cursor Settings → Plugins
workaround in README.md only; the seven READMEs/* locale files still
said auto-discovery always works. Mirror that fallback here so non-English
readers hit the same fix without hunting issue #172.

Evan Alferez · 2026-05-25 09:20:33 +09:00

47e9001634

Merge pull request #200 from AsimRaza10/fix/agent-model-omit-inherit

fix(agents): omit `model: inherit` so non-Claude tools don't see a bad model id

Yuxiang Lin · 2026-05-24 21:12:57 +08:00

470cc01dc5

docs(readme): note Cursor manual install fallback when auto-discovery fails (#199 )

Several users have reported that cloning the repo and opening it in Cursor
doesn't always trigger auto-discovery of the .cursor-plugin manifest. Add
the community-reported workaround (Cursor Settings → Plugins, paste repo
URL) to the Cursor section so it isn't only discoverable from issue
threads.

Closes #172

Yuxiang Lin · 2026-05-24 20:23:10 +08:00

a8a115dc36

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

fix(agents): omit model: inherit so non-Claude tools don't see a bad model id

`model: inherit` is a Claude Code-specific keyword that means "use the
parent session's model." Other tools that read the same agent frontmatter
(opencode, codex, etc.) don't understand it and instead try to use
`inherit` as a literal model id, which the configured provider rejects.

Reproduction (from #167): opencode + deepseek runs `/understand`, the
project-scanner subagent dispatches with `model: inherit`, deepseek
returns `ProviderModelNotFoundError`, and the pipeline halts on every
subagent dispatch.

With the field omitted, each platform falls back to its own configured
default:
- Claude Code: user's default subagent model
- opencode / codex / etc.: globally configured model

Note for Claude Code Opus users: subagents will no longer auto-inherit
the Opus session model. If you want the previous behavior, set your
default subagent model globally — that single setting now controls all
nine agents.

Closes #167

Asim Raza · 2026-05-24 10:50:26 +05:00

0566ea8b6b

docs(readme): note Cursor manual install fallback when auto-discovery fails

Several users have reported that cloning the repo and opening it in Cursor
doesn't always trigger auto-discovery of the .cursor-plugin manifest. Add
the community-reported workaround (Cursor Settings → Plugins, paste repo
URL) to the Cursor section so it isn't only discoverable from issue
threads.

Closes #172

Asim Raza · 2026-05-24 10:43:18 +05:00

0db7b3c795

Merge pull request #186 from AsimRaza10/fix/tailwind-source-detection

fix(dashboard): explicit @source for Tailwind v4 (fixes #179)

Yuxiang Lin · 2026-05-24 10:10:58 +08:00

42d70c3f9c

Merge pull request #187 from devangpratap/fix/progress-reporting

fix(ux): add progress reporting to /understand pipeline

Yuxiang Lin · 2026-05-24 09:58:52 +08:00

be458664c1

docs(readme): document incremental updates, subdir scoping, and tree-sitter+LLM split

Add to all 8 READMEs (English + 7 translations):
- "Keep learning" section gets inline commands for incremental re-runs, the --auto-update post-commit hook, and scoping /understand to a subdirectory for huge monorepos
- "Under the Hood" gets a new "Tree-sitter + LLM hybrid" subsection explaining the deterministic-vs-semantic split that powers the pipeline

Lum1104 · 2026-05-24 09:34:54 +08:00

dbba0703a9

fix(ux): add progress reporting to /understand pipeline

Adds phase status lines, batch progress with total count, and phase
completion confirmations to the skill definition. Users now see
[Phase N/7] headers and Batch X/N during analysis instead of
unnumbered batch lines with no context.

Fixes #182

devangpratap · 2026-05-23 14:18:26 -04:00

31ae12b65c

fix(dashboard): add explicit @source for Tailwind v4 detection

Tailwind v4's default source detection walks the nearest .git and
collects tracked files via git ls-files. When the dashboard sources
sit inside a gitignored subtree of an ancestor repo (e.g. the default
marketplace install path ~/.claude/plugins/cache/, which is ignored by
~/.claude/.gitignore), detection returns 0 files and the Oxide engine
skips all utility generation — the dashboard renders unstyled.

Adding explicit @source directives is the supported Tailwind v4 escape
hatch and is a no-op for installs where automatic detection works.

Verified: built CSS bundle jumps from ~9 KB to ~55 KB and utility
classes (.flex, .grid, .absolute, .w-full, .h-full) are present.

Fixes #179

Asim Raza · 2026-05-23 18:23:17 +05:00

96c412bcc1

Merge pull request #171 from Derrick-xn/docs/update-skill-graph-reference

docs(skills): update graph structure references

Yuxiang Lin · 2026-05-23 16:10:55 +08:00

35699dd82b

Merge pull request #177 from vedrao/fix/security-astro-vite-cve-bumps

chore(deps): bump astro to 6.3.7 and dashboard vite to 6.4.2 for security fixes

Yuxiang Lin · 2026-05-23 16:05:54 +08:00

58f66be006

chore(dependencies): update astro and vite versions in package.json and pnpm-lock.yaml

Bumps astro to version 6.3.7 and vite to version 6.4.2 across relevant package files to ensure compatibility and access to the latest features.

Ved Prakash · 2026-05-23 15:58:37 +08:00

4ef12f39a6

Merge pull request #161 from okwn/contrib/understand-anything/eslint-tooling

chore: add ESLint tooling with TypeScript support

Yuxiang Lin · 2026-05-23 15:47:52 +08:00

4bd6f78dff

chore(lint): switch to recommended baseline, fix errors, wire into CI

- typescript-eslint preset: strict -> recommended for a usable first-pass
  baseline (per PR discussion); ratchet up in a follow-up.
- Drop the projectService/parserOptions block. Neither `recommended` nor
  `strict` is type-aware, so it was unused; removing it also avoids the
  pnpm-workspace tsconfig-resolution failure mode flagged in review.
- Add Node + browser globals via the `globals` package so .mjs scripts and
  the dashboard stop hitting `no-undef`.
- Expand ignores: built bundles (**/public/**), Astro generated (.astro/),
  and .private/ (eval scratch). Cuts 2400+ errors in vendored output.
- Allow `_`-prefixed unused vars/args/caught errors; skip irregular
  whitespace inside comments (json-parser intentionally embeds ZWSP-escaped
  block-comment examples in JSDoc).
- Fix the residual 13 genuine errors: drop dead imports/vars, replace
  two `as any[]` in schema.ts with `Array<Record<string, unknown>>`,
  drop unused destructure in change-classifier, drop unused catch binding
  in extract-structure.mjs.
- Add EOF newline to eslint.config.mjs.
- Refresh pnpm-lock.yaml.
- Add `pnpm lint` step to .github/workflows/ci.yml so the tooling
  actually enforces something.

pnpm lint now exits 0 locally; 33+13 test files / 1445 tests still pass.

Lum1104 · 2026-05-23 15:26:39 +08:00

a1261b4883

Merge pull request #175 from zichen0116/fix/wrong-github-url-in-footer

fix: correct GitHub URL in onboarding guide footer

Yuxiang Lin · 2026-05-22 22:06:27 +08:00

f51727526d

fix: correct GitHub URL in onboarding guide footer

The generated onboarding markdown linked to a nonexistent repository
(anthropics/understand-anything) instead of the actual project URL
(Lum1104/Understand-Anything).

Ubuntu · 2026-05-22 20:23:21 +08:00

11c5123d61

docs(skills): update graph structure references

初晨 · 2026-05-22 12:08:44 +08:00

a30c226bf4

Merge pull request #170 from Lum1104/feat/trendshift-badge

feat(readme,homepage): add Trendshift trending badge

Yuxiang Lin · 2026-05-22 08:28:45 +08:00

17eed78876

feat(readme,homepage): add Trendshift badge

Adds the Trendshift trending-repository badge just below the tagline on the
English README and all 7 localized variants, and to the homepage hero between
the action row and the Enterprise pill.

Lum1104 · 2026-05-22 08:27:43 +08:00

33728f04a6

Merge pull request #164 from Lum1104/feat/community-video

feat(readme,homepage): add Community section with Better Stack walkthrough video

Yuxiang Lin · 2026-05-21 20:01:23 +08:00

ea4d17b484

feat(readme,homepage): add Community section featuring Better Stack walkthrough video

Adds a Community section near the end of README (English + 7 localized
variants) and a CommunityVideo component on the homepage embedding the
YouTube walkthrough by Better Stack. Section invites future video / blog /
tutorial contributions to be featured here.

Lum1104 · 2026-05-21 19:57:09 +08:00

db94d066a8

Merge pull request #163 from Lum1104/fix/extract-structure-symlink-isCli

fix(skills/understand): extract-structure isCli silently no-ops via symlinked SKILL_DIR

Yuxiang Lin · 2026-05-21 19:40:01 +08:00

300056e789

chore(release): bump version to 2.7.4

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

d14d6f8f96

fix(skills/understand): canonicalize isCli paths so symlinked SKILL_DIR runs main()

import.meta.url resolves through symlinks but pathToFileURL(process.argv[1])
preserves them, so extract-structure.mjs silently exited 0 without writing
output when invoked via the plugin's symlinked install path — the documented
Claude Code / Copilot CLI layout. Compare both sides via realpathSync and add
a post-write existence assertion plus caller-side guidance in the agent.

Closes #162

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

8a78c94fc6

chore: add ESLint tooling with TypeScript support

The repository has a pnpm lint script running 'eslint .' but ESLint
and typescript-eslint were not listed in devDependencies.

Added:
- eslint (^9.0.0)
- @eslint/js (^9.0.0)
- typescript-eslint (^8.0.0)

Added eslint.config.mjs with flat config (ESLint 9+) using
typescript-eslint strict rules. Ignores node_modules, dist, build,
and framework-specific output directories.

okwn · 2026-05-21 09:15:15 +00:00

1bbfe99c64

Merge pull request #155 from nieao/feat/onboarding-overlay

feat(dashboard): first-visit onboarding overlay

Yuxiang Lin · 2026-05-21 11:09:34 +08:00

58411ac1f7

refactor(onboarding): theme tokens, lifted state, a11y

- Replace hardcoded hex with var(--color-*) and CJK font stacks with
  var(--font-sans) / var(--font-heading) so the overlay tracks the theme
  picker and uses the project's typography (DM Serif Display).
- Lift dismiss/visibility state to Dashboard (shouldShowOnboarding +
  showOnboarding useState + dismissOnboarding callback). Gate the
  Suspense mount with a boolean so the lazy chunk is only fetched on
  first visit, matching the PathFinderModal / KeyboardShortcutsHelp
  mount pattern.
- Add capture-phase Escape handler (stopPropagation prevents the global
  shortcut chain from also firing) and role="dialog" / aria-modal /
  aria-labelledby on the card for screen readers.

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

9dfcce73a5

fix(onboarding): include class/function in node-type description

Schema (packages/core/src/schema.ts) defines node types: file, function,
class, module, concept, config, document, ... The welcome step body only
listed "file, concept, entity, claim", missing the most common code-side
types. Updated all 6 locales (en / zh / zh-TW / ja / ko / ru) to mention
file / class / function from code plus concept / entity / claim from the
knowledge wiki.

Lum1104 · 2026-05-21 11:06:54 +08:00

a29585874e

fix(onboarding): wire to i18n + add missing ua-fade-in keyframes

- Replace hardcoded Chinese strings with t.onboarding.* via useI18n
- Add `onboarding` namespace to en / zh / zh-TW / ja / ko / ru locales
- Inject @keyframes ua-fade-in (was referenced in inline style but
  never defined, so the overlay popped in instead of fading)

Lum1104 · 2026-05-21 10:56:10 +08:00

8f85b85679

Merge branch 'main' into feat/onboarding-overlay

Lum1104 · 2026-05-21 10:33:16 +08:00

cd09d4fe09

chore: remove Product Hunt promo from README and homepage hero

Lum1104 · 2026-05-20 08:53:03 +08:00

57a25ed4aa

feat(i18n): add Russian language support

Lum1104 · 2026-05-19 15:01:43 +08:00

v2.7.3 9d1318a0e7

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

fix(skills/understand): bundle build-fingerprints.mjs and reorder Phase 7

The Phase 7 step 2.5 code example in SKILL.md called
buildFingerprintStore() with 2 arguments, but the real signature
requires 4 (projectDir, filePaths, registry: PluginRegistry,
gitCommitHash: string). It also omitted the required
`await TreeSitterPlugin.init()`. Any LLM following the example
threw TypeError on `registry.analyzeFile()` and never produced a
baseline — which is why fingerprints.json never existed in a usable
form after a fresh /understand, and is the root cause behind
issue #152's "every auto-update escalates to FULL_UPDATE" cascade.

Replace the LLM-written script with a bundled `build-fingerprints.mjs`
that mirrors `extract-structure.mjs`: resolves @understand-anything/core
via createRequire, initializes TreeSitterPlugin + PluginRegistry
correctly, calls buildFingerprintStore with all four arguments, and
persists via saveFingerprints. Smoke-tested on this repo (3 files,
correct functions/classes/imports extracted).

Reorder Phase 7 so fingerprints are written BEFORE meta.json. If
fingerprint generation fails, the new step explicitly says to abort
Phase 7 — meta.json must not advance without a valid baseline, or
the next auto-update sees a fresh commit hash with no fingerprints
and classifies every file as STRUCTURAL.

Affects every install since 2.7.0 (when the broken example was
introduced). Users running /understand --full on 2.7.3+ will get
a usable fingerprints.json on the first try.

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

e7af9ae35e

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

fix(hooks/auto-update): make fingerprints merge unambiguous in Phase 3d

Fixes #152. Phase 3d step 3 instructed the LLM to "merge with existing
fingerprints (keep unchanged files as-is)" but the prose was vague
enough that the LLM-written script frequently wrote only the freshly
re-analyzed batch entries to fingerprints.json, discarding every other
file's fingerprint. The next auto-update saw N-batch_size files with
no stored fingerprint → classified as STRUCTURAL → exceeded the 30-file
threshold → FULL_UPDATE permanently, burning hundreds of thousands of
tokens on every subsequent commit.

Replace the four-bullet description with an explicit LOAD-PATCH-SAVE
script template:

  1. LOAD ALL existing entries from fingerprints.json (never skip).
  2. PATCH or REMOVE each path in filesToReanalyze (inline deletion
     handling so the spec doesn't need a separate deletedFiles list).
  3. GUARD: if the file existed and was non-empty but loaded as {},
     abort the write — silent load failure would otherwise clobber
     every fingerprint.
  4. SAVE the full dict back.

The reporter's dry-run showed this restores 81/97 files to COSMETIC
classification on their project (zero LLM tokens) instead of all 97
incorrectly forced into STRUCTURAL.

Note: a related ordering bug exists in skills/understand/SKILL.md
Phase 7 (meta.json written before fingerprints.json — silent failure
in step 2.5 leaves stale fingerprints). That's a separate fix in a
different file and is intentionally not bundled here.

Lum1104 · 2026-05-18 09:58:45 +08:00

dd8b724c99

fix(hooks/auto-update): apply .understandignore exclusions in Phase 0

Fixes #153. Phase 0 step 7 filters changed files to source extensions
only and never reads `.understandignore`, so files in user-excluded
paths (migrations, vendored code, tests) count as structural changes
and can spuriously escalate the action to FULL_UPDATE. The reporter
saw 50 → 38 structural files after applying their ignore patterns
(below the 30-file FULL_UPDATE threshold, ARCHITECTURE_UPDATE would
have sufficed).

Add step 9 that delegates to `createIgnoreFilter` from
`@understand-anything/core` via $CLAUDE_PLUGIN_ROOT. Same code path
as /understand's project-scanner Step 2.5, so the auto-update honors
the exact same patterns (hardcoded defaults + user .understandignore
files at both standard locations + `!` negation semantics).

If $CLAUDE_PLUGIN_ROOT can't be resolved, fail loud rather than
silently skipping — a silent skip reproduces the original bug.

Lum1104 · 2026-05-18 09:58:11 +08:00

5304ff06f3

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

fix(skills/understand): persist canonical edge direction during merge

Fixes #140. merge-batch-graphs.py already defaulted missing `direction`
to "forward" when building the dedup key, but the value was never written
back onto the edge — so the generated knowledge-graph.json shipped without
the field and the dashboard validator emitted one auto-correction per
edge (153k on the reporter's Go codebase).

Mirror the dashboard schema validator at packages/core/src/schema.ts:
lowercase the value, map "both"/"mutual" → "bidirectional", fall back to
"forward" for missing or invalid values, and persist the result onto the
edge before it enters edges_by_key. This also closes a latent dedup leak
where "Forward" and "forward" (or "both" and "bidirectional") would have
produced separate dedup keys.

Lum1104 · 2026-05-18 09:27:06 +08:00

f71bad5267

Merge pull request #139 from nieao/fix/windows-compat

fix(understand-knowledge): Windows path + zod schema null compatibility

Yuxiang Lin · 2026-05-17 22:07:38 +08:00

a5644ca3b0

Merge pull request #147 from rustanacexd/fix/understand-domain-plugin-root

fix(skills/understand-domain): resolve plugin root for agent prompt loading (#146)

Yuxiang Lin · 2026-05-13 10:20:33 +08:00

cde871990c

fix(skills/understand-domain): resolve plugin root at runtime for symlink installs

Fixes #146. Ports the $PLUGIN_ROOT resolution pattern from understand/SKILL.md
to understand-domain/SKILL.md, including:
- Symlink resolution for ~/.agents/skills/understand-domain
- Copilot fallback for ~/.copilot/skills/understand-domain
- Detailed error diagnostics listing all checked paths
- Phase 4 agent prompt path now uses $PLUGIN_ROOT/agents/domain-analyzer.md

Rustan Corpuz · 2026-05-12 15:00:55 +08:00

fafb888422

docs(homepage): add author homepage link below enterprise contact

A second pill mirroring the Enterprise one, linking to https://lum.is-a.dev/.
Same gold/amber styling, 0.6rem gap below the Enterprise pill so the two read
as one "contact" group, anim-5 so both pills enter together. Full mobile
breakpoint mirror.

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

Lum1104 · 2026-05-12 15:00:44 +08:00

9ab6724dca

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

Merge pull request #145 from zhushen12580/fix/code-review-feedback

docs: Add --language parameter documentation to all READMEs

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

8b96a8b1ce

543 Commits