FI ForgeIndex Manual

Manual

ForgeIndex User Manual

This manual summarizes the current user-facing behavior of ForgeIndex.

ForgeIndex User Manual

This manual reflects the current user-facing behavior of ForgeIndex.

Core Capabilities

  • Recursive scan/index into SQLite with stale-index cleanup.
  • Domain/kind/subkind file classification.
  • Model-root browsing with SQL-backed filtering, sorting, and paging.
  • Branded Windows startup flow (Windows 11 app icon + centered splash screen shown before main UI on the same monitor as the main window).
  • Startup workspace persistence for last-used monitor, maximized/restored state, window bounds, and left/right pane proportions.
  • Folder tree + Gallery surface (virtualized list/tile).
  • 3D/image/text previews, open-only routing, and external tool launch.
  • Embedded slicer project thumbnail extraction with image-first preview layout and compact expandable text summary.
  • Automated STL print-detail analysis that estimates minimum meaningful feature size, detail score, and printer-fit hints from mesh geometry instead of misleading 8K/12K labels.
  • Broad external-tool discovery (maker/CAD/EDA/slicer/vector/image apps) with extension-aware launch routing.
  • Manual/auto tags, categories, favorites, print-type controls.
  • Layered dictionary inference (v2 + v1 compatibility).
  • Multi-library isolation (separate DB and runtime storage per library root).
  • Optional guided setup with first-run onboarding, skip/don't-show-again behavior, and replay from the Help menu.
  • Data intelligence tools (classification integrity, aliases, signatures, mesh stats).
  • Health/Data Quality dashboards and DB health maintenance UI.
  • Offline ONNX/PT vision tagging (CUDA/CPU/Auto), with library-scoped profiles, staged pending review, runtime-path override, and report.
  • Comprehensive report generation (Markdown/JSON) and operation audit trail.

Guided Setup

ForgeIndex includes an optional built-in guided setup that introduces the normal workspace without changing data by itself.

  • It can appear on first launch.
  • It can be skipped.
  • The user can choose not to show it automatically again.
  • It can be reopened later from Help -> Guided Setup / Tour....
  • It points at the real main UI so users learn the normal workflow in place.

Optional AI Add-ons

ForgeIndex's AI subsystem is completely optional and additive. The core app still works normally with no AI runtime, no models, and no context packs installed.

  • Global master switch plus per-library AI enablement keep the AI lane opt-in.
  • Manifest-backed runtime/model/context packs are discovered under %LOCALAPPDATA%\TerkWerX\ForgeIndex\ai\packs, validated, and surfaced as installed, usable, and active states.
  • Manual selected-image-only vision analysis stores results in separate ai_* tables without touching scan/index flows.
  • Selected-image review and the current-library review queue manage stored AI annotations with unreviewed, accepted, and rejected states.
  • Accepted AI labels can be explicitly promoted into normal manual tags, including one-at-a-time alternate-label promotion, with duplicate-safe writes and an AI provenance badge on promoted tags.
  • Accepted primary AI labels can also be explicitly mapped into the existing folder-category lane for the selected image.
  • No automatic inference, no background AI processing, and no automatic conversion of AI output into core metadata.

Library-Isolated Mode (Multi-Library)

ForgeIndex supports physically separate, strictly isolated libraries (for example one per drive/root).

Marker Folder

Each library root owns:


<library-root>\.forgeindex

Key files in that marker folder:


<library-root>\.forgeindex\library.manifest.json
<library-root>\.forgeindex\<library-db>.db

<library-db>.db is manifest-controlled (not always a fixed filename).

Startup, Discovery, and Hotplug

  • Known library roots + last-active library are tracked in:

%LOCALAPPDATA%\TerkWerX\ForgeIndex\libraries-state.json
  • On startup, ForgeIndex discovers libraries from known roots and connected drives containing .forgeindex\library.manifest.json.
  • If a new drive appears while ForgeIndex is already running, it prompts to:
  • inspect or ignore the drive
  • load existing library if a manifest is found
  • create a fresh library if none exists

Strict Library-Local Guardrails

When Libraries -> Strict Library-Local Mode is enabled:

  • scan/open-db actions are blocked unless an active library is selected
  • fallback cross-library database workflows are blocked
  • status messaging explains why actions were blocked and how to attach/create a library

First-Run and Relocation Wizards

  • First-run setup wizard (Library Setup Wizard) can auto-suggest non-system drives, create/attach a library, and optionally start initial scan.
  • Metadata relocation wizard (Libraries -> Relocate Current Library Metadata...) can move DB/caches from fallback app-data storage into the active library marker folder.

Library UI Workflow

  • Libraries -> Attach or Create Library...
  • Libraries -> Register Current Scan Root as Library
  • Libraries -> Rename Current Library...
  • Libraries -> Refresh Connected Libraries
  • Libraries -> Remove Current Library from Catalog
  • Libraries -> Start Fresh Workspace...

The left library strip includes a + tab button to create a fresh library directly.

Isolation Guarantees

  • Active tab/library selects the active DB.
  • Scan root and scans are constrained to active library root.
  • Open DB is blocked for cross-library DB paths while a library is active.
  • Libraries do not share rows/tags/categories because each uses its own DB file.

Storage Model and Paths

ForgeIndex now has two storage modes:

  • Library-bound mode (preferred): runtime metadata follows the library under <library-root>\.forgeindex.
  • Fallback mode: local app-data storage when no library is active.

Runtime Roots

  • Runtime storage root is resolved by:
  • active library marker folder, else
  • %LOCALAPPDATA%\TerkWerX\ForgeIndex
  • A fresh workspace DB path prefers a non-system local drive when available:
  • \<drive>\.forgeindex\workspace-default.db
  • falls back to %LOCALAPPDATA%\TerkWerX\ForgeIndex\forgeindex.db if needed

Common Paths (Library-Bound)


<library-root>\.forgeindex\<library-db>.db
<library-root>\.forgeindex\preview-cache\...
<library-root>\.forgeindex\dictionaries\...
<library-root>\.forgeindex\safety-net\...

Local Profile Paths (Always Local)

Crash and diagnostics logs remain local to the user profile:


%LOCALAPPDATA%\TerkWerX\ForgeIndex\logs\crash-YYYYMMDD.log
%LOCALAPPDATA%\TerkWerX\ForgeIndex\logs\preview-extractor.log

Vision PT export cache/venv also uses local profile storage:


%LOCALAPPDATA%\TerkWerX\ForgeIndex\vision-cache

Window placement persistence also remains local to the user profile:


%LOCALAPPDATA%\TerkWerX\ForgeIndex\window-placement.json

Storage Policy UI

Use:

  • Preferences -> Storage Policy...

This shows resolved runtime paths for the active library/session, with copy/open actions.

Scanning and Indexing

Pipeline

  1. Pass 1 counts folders/files for totals.
  2. Pass 2 indexes into SQLite with batched writes and transactions.

After scan finalize:

  • stale folders under the scanned root are removed by run id
  • folder search index is refreshed for that root
  • background workers run only after user action arms automation (for example scan/toggle); startup and library switches keep them paused until then

Traversal Exclusions

  • hidden/system/reparse-point directories
  • System Volume Information
  • $RECYCLE.BIN

Scan Monitor

  • live progress and ETA
  • streaming log
  • encountered-extension legend
  • extension CSV export
  • fullscreen (F11, Esc)

Background Incremental Indexing

Toggle in:

  • Preferences -> Background Incremental Indexing

Current behavior watches the active scan root context and schedules debounced incremental scans.

Classification

Classifier output:

  • domain
  • kind
  • subkind

Current domain vocabulary:

  • Mesh, CAD, Slicer, CNC, Electronics, Images, Media, Code, Documents, Metadata, Archive, Other

Unknown extensions are indexed as Other.

Filtering, Search, Sorting, and Paging

Model-root query supports:

  • text search (FTS5 prefix matching)
  • optional doc-content search (Search docs)
  • domain/kind/tag/category filters
  • favorites-only, has-images-only, hide-noise, hide-NSFW
  • minimum model/image constraints
  • result limit + page navigation
  • sort: Model Count, Highest Richness

Limit clamp:

  • 50..50000

When Search docs is enabled, content search is applied to selected, small metadata docs:

  • README.txt, README.md, description.html, info.txt
  • size cap: 256 KB

NSFW filtering still applies.

Folder/Model Surface

  • Generic container folder collapsing (stl, obj, models, etc.) for display.
  • Ecosystem strip: CAD -> Mesh -> SlicerProject -> SlicedOutput -> GCode.
  • Richness score (0..100) with weighted signals.
  • Folder summaries include models/images/files/prints/subfolders/favorite.
  • dedicated gallery tab with list/tile modes
  • virtualized rendering (VirtualizingWrapPanel + virtualized DataGrid)
  • chunked keyset paging (no load-all)
  • debounce + cancel search updates
  • thumbnail size slider (persisted)
  • async thumbnail loading with LRU memory cache
  • multi-select (Ctrl/Shift + additive checkbox support)
  • bulk tagging/move/delete actions with safety-net flow and undo

Image-to-Model Linking

  • explicit image/model link table: image_model_links
  • deterministic “Go to model files for this image” resolution order:
  1. explicit link
  2. image folder if model root
  3. nearest parent model root
  4. fallback image folder
  • auto-link suggestions based on path/name similarity + confidence

Cover Images

  • per-model-root cover image support (model_root_cover_images)
  • assign from gallery/context workflows

Preview and Open Routing

Preview Capability Routing

  • InternalPreview
  • ExternalViewerRequired
  • OpenOnly
  • NoPreview

Internal Preview

  • 3D mesh: .stl, .obj, .3mf
  • image preview pipeline
  • text snippet preview: .txt, .md, .log (read-only, capped)

Embedded Slicer Preview Extraction

Supported image extraction for:

  • .lys, .lyt, .chitubox, .factory, .curaprofile

Includes cache/fallback handling and diagnostics logging.

When an embedded slicer thumbnail is available, ForgeIndex prioritizes that image in the main preview surface and keeps the textual project summary collapsed under a compact Project Summary expander until needed.

Open-Only

  • .html, .htm (browser)
  • .url (parses URL=...)
  • .pdf (default PDF handler)

External Viewer Categories

  • Slicer
  • VectorEditor
  • ImageEditor
  • Browser
  • CADViewer
  • EDA
  • PDFViewer

Each tool supports executable path, argument template, optional extension list, and per-category default.

SolidWorks Optional Preview

  • .sldprt / .sldasm can be converted to cached .stl when FreeCADCmd.exe is available via PATH or FORGEINDEX_FREECADCMD_PATH.

Large STL Handling

  • warning threshold around 1,000,000 triangles for preview path
  • preview-only decimation for very large meshes
  • source files are never modified

STL Print Detail Analysis

ForgeIndex now runs background STL detail analysis as part of mesh-stat enrichment.

  • Geometry-derived metrics include triangle count, sampled triangle count, bounds, surface area, triangle density, edge-length distribution, curvature complexity, thin-feature score, surface smoothness, mesh cleanliness, estimated minimum meaningful feature size, and a composite detail score (0..100).
  • The system is intentionally geometry-first: it does not label meshes as 8K, 12K, or 16K. Instead it estimates the smallest meaningful features in the STL and stores coarse Resolution Benefit Class / Recommended Printer Type hints.
  • Legacy rows and changed STL files are automatically re-analyzed when the file mtime, file size, or analysis version changes.
  • The model-files grid now exposes Dtl and Min mm columns for analyzed STL files, and the cell tooltip summarizes the score, minimum feature size, benefit class, and printer recommendation.
  • Histogram payloads for feature sizes and curvature distributions are stored in SQLite for future graphing/report workflows.

Screenshot Capture

  • Save Screenshot writes PNG into selected folder
  • collision-safe auto naming
  • immediate DB index update of saved image

Tagging and Dictionary Inference

Automatic Theme/Tag Inference

  • tokenizes folder/file names
  • removes noise tokens
  • matches dictionary terms
  • writes auto tags with confidence/rule metadata
  • re-derives auto tags on scan
  • manual tags remain untouched

Layered Dictionary Model (v2)

Layers merged in order (later wins):

  • Base: Assets/TagInference/tag-dictionary.base.json
  • Community: <storage-root>\dictionaries\tag-dictionary.community.json
  • User: <storage-root>\dictionaries\tag-dictionary.user.json
  • Additional *.json files in dictionaries folder load alphabetically between Community and User.

Merged snapshot:

  • <storage-root>\dictionaries\tag-dictionary.merged.json

Validation includes schema, references, confidence bounds, and fallback to last-known-good snapshot if needed.

Dictionary UI and Tooling

  • dictionary hash display in main toolbar
  • reload/info actions
  • developer tool:

dotnet run --project tools/ForgeIndex.DictionaryTool -- validate Assets/TagInference/tag-dictionary.base.json
dotnet run --project tools/ForgeIndex.DictionaryTool -- normalize Assets/TagInference/tag-dictionary.base.json
dotnet run --project tools/ForgeIndex.DictionaryTool -- add-term Assets/TagInference/tag-dictionary.base.json --term "spider-man" --tags fr.marvel,char.spiderman --group "Marvel Characters"
dotnet run --project tools/ForgeIndex.DictionaryTool -- convert-v1 old-dict.json new-dict.json
dotnet run --project tools/ForgeIndex.DictionaryTool -- merge base.json community.json user.json

Offline Vision Tag Enrichment (ONNX/PT)

Vision can enrich tags offline from either .onnx or .pt model selection.

Providers

  • Auto (tries CUDA first, then CPU fallback)
  • CUDA
  • CPU

Model Inputs and Resolver

  • .onnx path: used directly.
  • .pt path: auto-exported to ONNX and cached, then inferred through ONNX Runtime.
  • PT export uses a managed cache/venv pipeline under:

%LOCALAPPDATA%\TerkWerX\ForgeIndex\vision-cache
  • Export cache key includes source path + write-time + file length + export arguments.
  • Resolver diagnostics include cache hit/miss, chosen python, venv path, pip output, export command, and resolved ONNX path.

Labels Resolution

For each run, labels are resolved in this order:

  1. Active profile labels file override (if present and exists)
  2. PT cache labels (<cacheKey>.labels.txt) when source is .pt
  3. ONNX sibling labels:

model.labels.txt -> model.txt -> labels.txt

  1. fallback generated class names (class_{id})

Library-Scoped Vision Profiles

  • Profiles are stored in each library DB (VisionModelProfiles) and do not leak across libraries.
  • Active profile id is stored per library (vision_active_profile_id in settings).
  • Profile fields include model path, provider, optional Python override, export options (opset/imgsz/simplify/nms), and optional labels path.
  • Switching libraries switches the active vision profile context automatically.

Data Model

  • run/file processing state: file_visual_tag_runs
  • pending and reviewed detections: vision_detections
  • committed tag candidates: file_visual_tag_candidates
  • per-profile confidence overrides: vision_profile_label_confidence_overrides
  • committed file tags use source AutoVision

Pending Review Workflow (Two-Phase)

  • Inference stages detections as pending (is_pending=1) rather than writing final tags immediately.
  • Pending review supports:
  • label click filter and confidence sort
  • live photo stream filtering by selected label
  • multi-select + Select all filtered
  • bulk pending edits:
  • remove label
  • replace label
  • add label
  • set per-profile minimum confidence override
  • Finalization actions:
  • Commit Pending converts non-rejected pending detections into final candidates/tags
  • Discard Pending rejects/removes pending review state
  • Commit/discard operations are transactional and idempotent.

Single Active Pending Batch Rule

  • Pending scope is model-identity specific (model path/file stamp + labels + provider + profile scope + PT export args).
  • Normal start is blocked while pending exists for the current model identity.
  • Explicit replace flow (Start New Run (Replace Pending)) discards current pending first, then stages a new run.
  • Service-layer guardrails enforce this rule for UI and non-UI entry points.

Runtime Behavior

  • Vision enrichment loop is background/cancellable, but remains paused until background automation is armed by user action.
  • While pending review exists for the active model identity, background inference pauses and reports a pending-review status instead of continuing.
  • Manual batch runs can still be launched from the Vision menu/control center, subject to pending-review guardrails.

UI

  • Vision -> Vision Control Center...
  • Vision -> Vision Tagging Settings...
  • Vision -> Vision Results Report...
  • Vision -> Run One Vision Batch Now

Vision Control Center

  • active profile selector with add/edit/duplicate/delete
  • ONNX/PT model + labels + provider + threshold controls
  • CUDA/cuDNN runtime-folder picker (CUDA/cuDNN folder) to override native DLL discovery
  • optional Python executable picker for PT export
  • image-type profile selector with built-in model guidance (best-fit model strategy + expected threshold range)
  • one-click Apply action to set a profile-recommended threshold
  • live queue + throughput telemetry
  • rolling photo stream and detected-object counters
  • pending review banner and replace safety toggle
  • commit/discard and bulk pending-label edit actions
  • quick access to diagnostics and report

Vision Results Report

Report includes:

  • total runs (ok/error/pending)
  • top detected objects
  • top auto-applied tags
  • top run errors
  • runs by model
  • recent file-level outcomes

Export formats:

  • Markdown (.md)
  • JSON (.json)

Model Compatibility Notes

  • ForgeIndex uses Microsoft.ML.OnnxRuntime.Gpu (GPU package) and blocks accidental CPU-package-only reference at build time.
  • CUDA execution requires NVIDIA drivers plus compatible runtime dependencies discoverable by the process.
  • For current ONNX Runtime GPU setup in this repo (1.22.x), target CUDA 12 + cuDNN 9 + VC++ runtime compatibility.
  • If CUDA is unavailable, Auto transparently falls back to CPU execution.
  • Legacy saved provider value DirectML is normalized to Auto.
  • Supports classifier-style and YOLO-like rank-3 output patterns currently handled by runtime parsing.
  • Detects Git LFS pointer stubs and surfaces explicit model/labels configuration errors.
  • PT export requires Python + ultralytics tooling available (auto-provisioned in resolver venv when possible).
  • Output quality depends on model architecture, training domain, and labels taxonomy.

CUDA Runtime Folder Override

  • In Vision Control Center, set CUDA/cuDNN folder when your CUDA/cuDNN DLLs are not reliably found via system PATH.
  • The selected folder is persisted in settings (vision_runtime_bin_path) and prepended to process DLL search at runtime.
  • Clear Paths in the Vision Control Center clears model path, labels path, and the CUDA runtime-folder override.
  • Live Reactor diagnostics include runtime readiness text and dependency-status text; when dependencies are identifiable, missing DLL names are surfaced there.

Data Intelligence and Hygiene

Classification Integrity

  • integrated into comprehensive report (Markdown/JSON)
  • standalone check action:
  • Preferences -> Run Classification Integrity Check...
  • checks include drift, conflicts, unknown extensions, and noise distributions

Root Naming / Display Alias Tool

  • generic root detection + confidence + reason
  • display aliases in model_root_display_aliases
  • bulk apply/revert via:
  • Preferences -> Fix Generic Root Names...
  • display-only aliases (never renames disk folders)

Duplicate Structure Detection

  • structural signatures in model_root_signatures
  • ignore table model_root_signature_ignores
  • exact cluster grouping + near-duplicate similarity view

Mesh Stats Enrichment (STL-first)

  • stored in file_mesh_stats
  • includes triangle count + bounding box + timestamps
  • background worker, cancellable, with diagnostics counters
  • filtering and warning badges use these stats

Health Dashboard

Open:

  • Preferences -> Health Dashboard...

Views include roots with:

  • 0 images
  • 0 model files
  • large file counts
  • archive-only
  • metadata-only
  • untagged
  • missing cover image

Actions:

  • Open root
  • Assign cover
  • Tag
  • Add to ignore

Workflow:

  • double-click/Enter navigates main panel to the selected root
  • dashboard stays open for back-and-forth cleanup
  • optional auto-advance selection mode

Data Quality Dashboard

Open:

  • Preferences -> Data Quality Dashboard...

Tracks and repairs:

  • stale folder rows
  • broken file rows
  • orphan image-model links
  • untagged images
  • duplicate tags (case-insensitive)

Diagnostics, Maintenance, and Audit

Performance Diagnostics

Open:

  • Preferences -> Performance Diagnostics...

Includes live metrics for:

  • gallery query latency
  • thumbnail cache/decode activity
  • UI-thread stall warnings
  • classification integrity runtime
  • signature build runtime
  • mesh enrichment throughput/queue
  • vision enrichment throughput/queue
  • doc-search latency

Database Health Tools

Open:

  • Preferences -> Database Health Tools...

Actions:

  • integrity_check visibility
  • index stats
  • ANALYZE
  • VACUUM
  • backup
  • restore

Corruption Recovery Prompting

When SQLite corruption-like failures are detected (for example error 11 malformed image), ForgeIndex:

  • classifies as corruption
  • records audit event
  • guides user to Database Health Tools for restore/switch flow

Operation Audit Log

Open:

  • Preferences -> Operation Audit Log...

Tracks core operations including deletes, stale cleanup, tag/category edits, print-type changes, external launches, report generation, integrity checks, alias/signature actions, mesh/vision batches, and hygiene actions.

Comprehensive Report

Open:

  • Preferences -> Generate Comprehensive Report...

Output:

  • Markdown (.md) or JSON (.json)

Includes counts, coverage window, domain/kind/extension distributions, tag/category usage, print-type breakdown, top folders, integrity section, and recent audit activity.

External Tools

Open:

  • Preferences -> External Tools...

File context menus support Open, Open With..., Reveal in Explorer, Copy Path, browser-open actions, and category-specific Open in <Tool>....

Discovery and Routing

  • Discover Installed Tools now probes a wide signature set across slicers, CAD viewers, EDA suites, vector editors, and image editors.
  • Detection sources include:
  • common install roots (Program Files, Program Files (x86), local app install folders)
  • registry App Paths (HKLM/HKCU, including WOW6432Node)
  • registry uninstall metadata (HKLM/HKCU, including WOW6432Node)
  • Discovered tools can include extension profiles so launch selection stays file-type aware when multiple tools exist in the same category.

Startup Experience

  • On first launch, ForgeIndex opens maximized on the selected monitor with a centered splash image and branded Windows 11 icon before opening the main window.
  • On later launches, ForgeIndex restores the last-used monitor, maximized/restored state, normal window bounds, and left/right pane widths before showing the main workspace.
  • If the saved display layout is no longer available, the restored window bounds are clamped back onto an available monitor.
  • Splash visibility is intentionally delayed to remain on-screen for at least 3.5 seconds.

Known Limitations

  • Windows-only (WPF).
  • Internal 3D preview is limited to .stl, .obj, .3mf; other CAD/mesh formats use external tools.
  • Very large meshes can still be heavy to preview even with decimation safeguards.
  • Incremental indexing currently focuses on active-root workflows; multi-root scheduling/profiles remain future work.
  • Vision tagging quality is model-dependent and may produce low-value/no detections if model taxonomy does not match your dataset.
  • Vision runtime override is currently a single folder path; if CUDA/cuDNN DLLs are split across multiple folders, use system/user PATH in addition to the override.