Understand-Anything

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

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

docs: Add --language parameter documentation to all READMEs

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

208921be3b

Merge pull request #142 from zhushen12580/feature/language-parameter

feat: Add --language parameter for localized content generation

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

4c6f7c3e0b

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

feat(dashboard): Complete i18n translation for all UI components

zhushen · 2026-05-12 01:53:58 +08:00

a3ec91bf39

feat(install): add KIMI CLI platform support (#134 )

KIMI CLI scans ~/.kimi/skills/ (its brand path) for SKILL.md per the
official skill discovery spec, so distribution follows the same
folder-symlink pattern as Hermes / Cline / OpenClaw. install.sh and
install.ps1 register the `kimi` platform; README × 7 updated for the
one-line install title, <platform> values, and compatibility table.

Closes #134

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

Lum1104 · 2026-05-11 22:11:48 +08:00

31a775d65f

feat(install): add Cline platform support (#116 )

Cline natively scans ~/.cline/skills/ for SKILL.md, so distribution
follows the same folder-symlink pattern as Hermes / OpenClaw /
Antigravity. install.sh and install.ps1 register the `cline` platform;
README × 7 (English + 6 locales) updated for the one-line install
title, <platform> values, and the compatibility table.

Closes #116

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

Lum1104 · 2026-05-11 22:10:37 +08:00

b2fed42eac

feat(dashboard): allow ACCESS_TOKEN override via env var

Honor UNDERSTAND_ACCESS_TOKEN if set, falling back to the random 16-byte
hex token. Lets the dev token survive across server restarts so shared
dashboard URLs don't rot, and makes the auth path easier to script in
tests.

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

Lum1104 · 2026-05-11 22:02:58 +08:00

1779cbd9a7

fix: Wrap MobileLayout with I18nProvider; use outputLanguage key in config

P1: MobileLayout was missing I18nProvider wrapper, causing useI18n
    to throw error on mobile devices. Now both desktop and mobile
    layouts are wrapped with I18nProvider.

P2: SKILL.md used 'language' key but Dashboard reads 'outputLanguage'.
    Fixed config.json key name to match ProjectConfig type definition.

All tests passed:
- Core: 670 tests
- Dashboard: 42 tests

zhushen · 2026-05-11 20:30:50 +08:00

e1650f627c

535 Commits