Skip to content

feat(docs-flatten): describe every image a doc references, asking before large runs - #1794

Merged
diillson merged 3 commits into
mainfrom
fix/docsflatten-image-paths
Oct 15, 2026
Merged

diillson merged 3 commits into
mainfrom
fix/docsflatten-image-paths

Conversation

@diillson

@diillson diillson commented Oct 15, 2026 •

Copy link
Copy Markdown
Owner

Summary

A user's corpus had 711 images: 521 described, 49 not found, 135 unsupported format, 2 large diagrams skipped as logos/icons, and the default 50-image cap meant the first run described only 50.

Finding images

  • Percent-encoded paths (modelo%20de%20c%C3%A9lulas.png) are decoded; they were not found.
  • ![alt](<path with spaces.png>) and angle-bracket reference definitions are parsed; they vanished from the corpus.
  • Obsidian embeds ![[a.png]], ![[img/a.png|alt]], ![[a.png|300]] become image markers (notes/PDFs stay as written); a file named without its folder resolves by unique name under the root.

Formats and filters

  • BMP and TIFF are converted to PNG (pure Go, golang.org/x/image, already a dependency); .jfif/.jpe/.pjpeg/.pjp accepted. A skipped format is reported by extension (unsupported format .heic).
  • A logo/icon file name skips the image only when it is at most 512 px; a 1.6 MB "icons" image is content.

No default cap, ask before spending

  • maxImages is now an optional cap (default: all).
  • When a model calls the tool (agent loop, squad workers, MCP/ACP clients) and more than 20 images still need a description (cached ones are free and do not count), the run stops before describing and writes nothing, reporting the count and estimated tokens and telling the model to ask the user, then re-run with confirmImages=true, maxImages=N or images=markers. The user's own chatcli tool call is marked as direct use and runs.

Test plan

  • All reference forms resolve and are described; name index unique-only
  • Filters: large icons kept, BMP/TIFF reach the model as PNG, .jfif accepted, .heic reported by extension
  • Large run: model caller stops and writes nothing; maxImages=5 describes 5; cached images do not count; direct use and confirmImages=true run
  • chatcli tool marks direct use
  • go test ./... (plugins, cmd), golangci-lint, patch coverage 88.8%
  • Live: the encoded accented case and the other forms 5/5 described; coder on 25 new images stopped, reported count and cost, did not treat a non-interactive @ask default as consent and waited for the user

…kets or wiki embeds

An image whose name has spaces or accents is usually written
percent-encoded, which never matched the file on disk, so it was skipped
as not found and kept only its marker. Angle-bracket destinations with
spaces and Obsidian embeds were not recognized at all and vanished from
the corpus. Paths are now decoded, both forms are parsed, and a link that
names only the file resolves to it when the name is unique under the
root.
@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Quality Gate

Result: ✅ all floors passed

Floor Status Result Δ vs main Budget
1 · Build & Static ✅ go build / vet / fmt / lint — —
2 · Coverage ✅ 67.8% (bootstrap) 0 ≥ baseline
3 · Patch coverage ✅ 88.8% (req ≥ 60%) — ≥ 60%
4 · AI smells ✅ diff scanned — —
5 · Scope budget ✅ 8 files / 469 LOC (code 469 + tooling 0) — warn 800·25
6 · E2E ✅ go test -race ./e2e/... — ≤ 15min
7 · Commit lint ✅ conventional commits — —
8 · Cyclo (new code) ✅ 6 file(s) under threshold — ≤ 30
9 · Secrets scan ✅ gitleaks — —
10 · i18n parity ✅ missing 0, unknown 0 — —
11 · CRD drift ✅ drifted: 0 — —
12 · License headers ✅ 0 missing — —
13 · API breaking ✅ 0 incompatible — —
14 · Binary size ✅ chatcli 98.8MB · operator 55.4MB — 100MB each
15 · Provider parity ✅ 14 providers · 0 violations — —

Config: .github/quality-gate.yml. Workflow: .github/workflows/quality-gate.yml.

diillson and others added 2 commits October 15, 2026 12:50
…d BMP and TIFF

The 50-image cap described a fraction of a large corpus by default. It is
gone: maxImages is an optional cap. When a model calls the tool and more
than 20 images still need a description, the run stops before spending
and writes nothing, reporting the count and estimated tokens so the model
asks the user, then re-runs with confirmImages, maxImages or markers; the
user's own chatcli tool call runs directly. BMP and TIFF are converted to
PNG, JPEG variants are accepted, a skipped format is reported by
extension, and a logo or icon name only skips a small image.
@diillson diillson changed the title fix(docs-flatten): find images written with encoded names, angle brackets or wiki embeds feat(docs-flatten): describe every image a doc references, asking before large runs Oct 15, 2026
@diillson
diillson merged commit 29405e5 into main Oct 15, 2026
26 checks passed
@diillson
diillson deleted the fix/docsflatten-image-paths branch October 15, 2026 16:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant