Skip to content

Latest commit

 

History

History
449 lines (329 loc) · 21.3 KB

USER_GUIDE.md

File metadata and controls

449 lines (329 loc) · 21.3 KB
layout single
title User Guide
sidebar
nav
docs

This guide explains how to use StratoSort Stack day-to-day, including Smart Folders, Knowledge OS (search, chat, Relate, Atlas, timeline), Downloads triage, and key settings.

For installation help, use Install Guide. For testing and bug reporting, use the Tester Guide.


1) What StratoSort Does

StratoSort uses local AI to:

  • Analyze your files by content (not just filename)
  • Suggest where files belong
  • Rename files using your naming rules
  • Help you search by meaning, chat with your files, and see them on a graph or map
  • Watch Downloads or Smart Folders and suggest where new files belong

Processing stays on your machine after the one-time model download unless you turn on optional cloud AI in Settings (your own API keys). Embeddings always stay local.


2) Typical Workflow

{% include figure image_path="/assets/e2e-screenshots/01_welcome_screen.webp" alt="Welcome Screen" caption="The Welcome Screen where you start your journey." %}

StratoSort is organized into five phases. You move through them in order:

  1. Welcome — Start screen. Choose your flow.
  2. Setup — Create Smart Folders (the destination folders the AI routes files into). Give each folder a plain-language description so the AI knows what belongs there.
  3. Discover — Drag and drop files, or use the Select/Scan Folder buttons to browse. The AI analyzes content, extracts meaning, and generates organization suggestions.
  4. Organize — Review each suggestion. Accept, reject, or edit the destination and filename. Use Undo/Redo if you change your mind.
  5. Complete — Lists every file that was moved, with its new location, and how many files went to each folder. The folder button on a row shows that file in its folder, and Save list as CSV saves the list. Undo is still available here.

If a run does not move every file, you stay on Organize. A banner says how many files moved, how many did not and why. See every file lists each file and where it went, or why it was not moved, and Save list as CSV saves that list with each file's original and new location. The banner also shows on the Dashboard and stays until you dismiss it or start another run.

The step tabs in the top bar follow the same rules as each step's own Continue button. A tab you cannot open yet is dimmed, and hovering or focusing it tells you why (for example, from Welcome, Discover needs a Smart Folder first; Organize needs at least one analyzed file, or files you organized before; Complete needs at least one organized file). Going back to an earlier step is always allowed. While files are moving, or an undo or redo is running, the tabs pause until the work finishes, and so do the dashboard links, the Alt+arrow keys, File > Select Files and Select Folder, and the knowledge graph's Go to Discover. Settings stays available from the gear icon. Analysis does not pause the tabs: it keeps running when you open another step, so you can organize the files that are ready while the rest are analyzed, and you can stop it with Stop analysis on Discover or Organize. Switching to Dashboard waits until the analysis finishes.

Prefer one screen over steps? Choose Dashboard on the Welcome screen, or use the Guided / Dashboard toggle in the top bar, for a single overview screen. Guided (the phases above) is the default.


3) Smart Folders (Most Important First Setup)

{% include figure image_path="/assets/e2e-screenshots/03_setup_smart_folders.webp" alt="Smart Folders" caption="Set up your destination folders to guide the AI." %}

Smart Folders are destination folders that the AI routes files into. Each Smart Folder has a description that tells the AI what kind of files belong there. The AI compares your file's content against these descriptions to decide where it fits best.

Best practices

  • Create folders around real outcomes (for example: Invoices, Receipts, Screenshots, Contracts).
  • Write descriptions in plain language — pretend you're telling a coworker what goes in each folder.
  • Be specific. "Monthly bills and vendor invoices" works better than "financial stuff."
  • The app creates a single "Uncategorized" fallback folder by default on the first launch. You can change where it is, but not its name.
  • You must proactively create your own specific smart folders to instruct the AI where to sort files.
  • Start with 3-5 clear folders before adding more. Overlapping descriptions confuse the AI.

Good folder description examples

Folder Description
Invoices "Bills from vendors and monthly service invoices."
Tax Documents "W-2, 1099, tax forms, receipts needed for filing."
Project Specs "Requirements, architecture docs, and project briefs."
Screenshots "Screen captures, app screenshots, and UI mockups."

Writing folder descriptions

The AI reads each folder's name and description, and nothing else, to decide where a file goes, so a few words of description decide where many files land. It is normal to find a description too vague only after seeing where files land; that is what the sample below is for.

What to include:

  • The kinds of files that belong here, in the words those files use ("invoice", "W-2", "lease").
  • Who they come from or are about, when that tells folders apart ("from suppliers", "for the Garden Street house").
  • The most telling words first. Only the first part of a long description reaches the AI, and Setup says so when a description is cut off.

What to leave out:

  • Words every folder could use, such as "files", "documents", "stuff" or "misc".
  • Files that belong in another folder. If two folders are close, say what goes in this one and not the other ("Invoices from suppliers. Not receipts for things we bought.").

Example: a folder named Invoices with the description "Documents" leaves the AI with the name alone. "Bills and invoices from suppliers, with an amount due and a due date. Not receipts." tells it what belongs there and what does not.

Setup shows a hint under a description that is missing, short, cut off, or reads like another folder's. A hint never stops you from saving.

Try a few files first

When you add 20 or more files and your Smart Folders have not been tried since they last changed, StratoSort asks before it starts: Analyze 5 files first, or Analyze all of them. The sample takes files of each type in the batch. Nothing is moved.

When the sample is done, you see where each file would go, the confidence where there is one, and why. Then choose Analyze the other files to go on, or Edit Smart Folders to change a description first. The sample files count as analyzed, so the rest of the batch does not analyze them again. Files you have not analyzed yet stay in the queue on Discover.

StratoSort remembers that you saw a sample, or chose Analyze all, for the folders you have now. It asks again only after you change a folder's name, description or location.

When you change Smart Folders after files were analyzed

When you change a Smart Folder, Organize ranks the files waiting there again with the current folders, without analyzing them again. Most files get a current folder that way.

Some files can still point to a folder picked from your old Smart Folders: the folder the analysis picked when nothing else ranks the file. StratoSort does not move those unnoticed. Organize lists them above the files, with Analyze again to analyze only those files with the current folders, and Move asks before it moves any of them. StratoSort does not analyze them again on its own, because on a large batch that takes as long as the first run did. A folder you chose yourself on a card is never treated as out of date.

Teaching StratoSort

When you change a file's folder on Organize, its card says what StratoSort learns from that. StratoSort learns from a correction once the file is moved. After you move two different files of the same type and label from the folder it picked into the same other Smart Folder, it suggests your folder for the next such file. Its card then gives the reason You moved 2 similar files from "A" to "B", where A is the folder StratoSort picked and B is yours. One correction changes nothing. Undoing those moves takes it back, and so does moving as many such files away from your folder when StratoSort suggests it.

You can also type a rule in Settings > Performance > Memory & Rules (see Performance). A rule moves its folder up for files of that type when that folder is already one of the folders StratoSort considers for the file. It does not add a folder StratoSort did not consider. For a firm change, make the two corrections described above.


4) Naming Conventions

There is one default naming convention. You can change it in either of two places, and both show the same value:

  • Settings -> Default Locations -> File naming defaults (saved when you click Save).
  • The Naming strategy button in Discover (saved as soon as you pick an option).

The default applies to Discover's suggested names (already analyzed files update to match), the Download Watcher, the Smart Folder Watcher, and Reanalyze All Files. It is kept between sessions.

You can control:

  • Convention
    • subject-date
    • date-subject
    • project-subject-date
    • category-subject
    • keep-original
  • Date Format
    • YYYY-MM-DD
    • MM-DD-YYYY
    • DD-MM-YYYY
    • YYYYMMDD
  • Case
    • kebab-case, snake_case, camelCase, PascalCase, lowercase, UPPERCASE
  • Separator
    • Use safe separators like - or _

Tip: If you need maximum compatibility across apps and systems, prefer kebab-case plus YYYY-MM-DD.


5) Knowledge OS (search, chat, graph, map)

{% include figure image_path="/assets/e2e-screenshots/36_knowledge_os_indexed.webp" alt="Knowledge OS Search" caption="Search files by meaning, not just keywords." %}

Open Knowledge OS with Ctrl+K (Windows/Linux) or Cmd+K (macOS), or the Knowledge OS button in the nav.

Tabs:

  • Search — Natural language and keyword search ("invoices from last quarter").
  • Chat — Ask questions about your analyzed files; answers cite the source documents.
  • Timeline — Browse analyzed files by date.
  • Relate — Node-link graph of clusters and similarity edges.
  • Atlas — Map of the library: nearby dots are similar. Lasso a region to move, tag, or make a Smart Folder.

Relate vs Atlas

  • Relate is for "how do these files connect?" — follow edges, expand a cluster, inspect bridges.
  • Atlas is for a bird's-eye view — outliers, likely mis-files, bulk select.

Both use the same analysis. If search is empty, switch Settings to Advanced and use Rebuild all embeddings under Settings → AI Configuration.

Downloads triage

From Knowledge OS you can open Downloads triage: keep / trash / ambiguous buckets for a folder (usually Downloads), with a deeper scan for the ambiguous pile. Use it when the folder is messy and you want a review pass before auto-organize.


6) Settings Walkthrough

{% include figure image_path="/assets/e2e-screenshots/14_settings_panel_top.webp" alt="Settings Application" caption="Configuration and performance tuning." %}

Open Settings. Use Simple unless you need model, retrieval, or diagnostic controls — Advanced reveals those panels.

Experience and appearance

  • Simple / Advanced — Simple hides advanced configuration and uses a streamlined retrieval path. Files still embed on-device in the background.
  • Appearance — Theme and color.

AI Configuration

  • Local AI Engine: Model and GPU status. In Simple mode it also has Download recommended models.
  • Default AI models: Text, vision, and embedding models (Advanced).
  • Model Management: Download or add GGUF models (Advanced).
  • Embedding behavior / rebuild: Rebuild the index after changing the embedding model (Advanced).
  • Chat Persona: How the in-app assistant responds (Advanced).

AI Provider (optional cloud)

  • Off by default. With a cloud provider selected, document analysis, chat and organization suggestions use it; each of the three can be sent to a different provider, or kept local.
  • Audio and video analysis follow the Analysis provider: speech is still transcribed on your machine and the transcript is sent. A video also sends up to four frames, but only when "Describe video keyframes" is on and you have accepted the current consent text. The pixels of still images stay local.
  • Anthropic or any OpenAI-compatible endpoint (OpenAI, Ollama, LM Studio, vLLM, …).
  • Per-operation and per-Smart-Folder routing; a monthly spend cap per provider; self-hosted URLs count as $0.
  • API keys stay in the OS keystore. Embeddings always stay local.

See AI_PROVIDERS.md.

MCP Server (optional)

  • Off by default. Lets Claude Desktop, Cursor, Zed, or another MCP client search and chat with your local corpus. Loopback-only, bearer token, query text is not logged.
  • Once you tick Enable MCP server, it starts with StratoSort each time until you untick it. None of its tools moves, renames or deletes files.

See MCP_SERVER.md.

Performance

  • Auto-organize: Watch Downloads (and related routing).
  • Memory & Rules: Type a rule such as "CSV files go to Reports". It moves Reports up for CSV files when Reports is already one of the folders StratoSort considers for them. Two corrections teach a firm change (see Teaching StratoSort). Your corrections are listed here too; edit or delete any that are wrong.
  • Background Mode: Keep running in the tray.
  • Exclusion rules: Skip paths or patterns from watchers and triage.
  • Processing limits and Search enrichment (relationship expansion and the relationship index Rebuild button) (Advanced).

Default locations

  • Where new Smart Folders are created.
  • File naming defaults (convention, date format, case, separator).

Application

  • Launch on startup, notifications, and software updates. Installed builds check GitHub Releases for a new version at startup and every 4 hours; turn this off with Background update checks, or use Check for updates to check now. See Network Transparency.
  • License: commercial key status. Every feature works without a key.
  • About and Third-party notices.
  • Settings backup/restore (Advanced).
  • Troubleshooting logs live under Diagnostics (Advanced): snapshot, open/export logs, API tests, and the Show live activity switch (see Need to see logs).

Analysis history

  • Past analysis results and statistics.

7) AI Model Profiles

On first launch, the setup wizard offers two profiles:

Profile Text Model Vision Model Embedding Model Best For
Base (Small & Fast) Llama 3.2 3B LLaVA 1.6 Mistral 7B all-MiniLM-L6-v2 All computers, CPU-only, low memory
Better Quality Qwen2.5 7B LLaVA 1.6 Mistral 7B nomic-embed-text v1.5 Modern hardware, 16GB+ RAM, GPU

You can switch models later in Settings -> AI Configuration -> Default AI Models (switch Settings to Advanced first; Simple mode hides this panel). Base downloads about 7 GB and Better Quality about 10 GB.

Changing the embedding model requires an index rebuild. The app prompts you when this is needed, both in Settings and when you re-run the setup wizard with files already indexed.


8) Recommended Starter Configuration

If you want a safe default profile:

  • Start with the Base (Small & Fast) model profile
  • Enable Auto-organize
  • Keep confidence around 75-85%
  • Use naming convention subject-date
  • Use date format YYYY-MM-DD
  • Keep separators simple (-)

Then run a small batch first and review outcomes before scaling up.


9) Daily Usage Pattern

  1. Collect files in your intake location (for example your Downloads folder).
  2. Open StratoSort and go to the Discover phase. Drag files in or select a folder.
  3. Review the AI's suggested destinations and names.
  4. Move to Organize and approve, edit, or reject each suggestion.
  5. After organizing, open Knowledge OS (Ctrl+K / Cmd+K) to search, chat, or check Atlas/Relate.
  6. Use Undo/Redo in Organize or Complete if something doesn't look right.

10) Troubleshooting Quick Fixes

Search is weak or empty

  • Check Settings -> AI Configuration for model status.
  • Confirm embeddings exist and rebuild if needed.
  • Retry with a more specific query.

Auto-organize feels too risky

  • Increase confidence threshold.
  • Keep Smart Folders tightly defined.
  • Start with manual review before fully trusting automation.

File names are not what you expect

  • Review naming defaults in Settings -> Default Locations.
  • Confirm convention/date/case/separator values.

"That folder leads into a system folder through a link or short name."

You can see this when you use Create directory on a Smart Folder marked Missing in Setup. StratoSort creates folders on any drive, an external one included, but never inside a system folder. It goes by where the folder really is, not by the path as written. If the path runs through a shortcut-style link (a symbolic link, or a junction on Windows) or a Windows short name that leads into a system folder, the folder is refused.

  • Edit the Smart Folder to use a folder outside the system folders.

A folder that is not inside one of your Smart Folders or Documents is created after you confirm it in a prompt. If the path runs through a link, the prompt names the folder the link really leads to.

A folder can't be used on a Mac

If StratoSort says it is not allowed to open or write to a folder, open System Settings > Privacy & Security > Files and Folders, allow StratoSort, then choose the folder again. A read-only drive (for example one formatted for Windows, NTFS) cannot be a Smart Folder; choose a folder on another drive.

Need to see logs

  • Open Settings -> Diagnostics (Advanced) and use Open Folder or Export Logs.
  • Use Open Folder to browse logs or Export Logs to create a shareable file.
  • To watch what the app is doing as it happens, turn on Settings -> Diagnostics -> Show live activity or press Ctrl+Shift+L (Cmd+Shift+L on Mac); the shortcut works in Simple mode too. A small panel floats over the app:
    • Activity lists events in plain words ("Analyzing receipt.jpg", "Vision model ready", "Filed invoice.pdf", "Saved search index").
    • Raw shows the log lines themselves, with a minimum-level filter and a context filter. Click a line to see it in full.
    • Drag it by its title bar, resize it from the bottom-right corner, or focus the title bar and use the arrow keys (Shift+arrow keys resize). Minimize it to a small pill, pause it (new lines are counted and shown when you resume), copy the visible lines, or clear it. Its position, size and tab are remembered on this computer.
    • It shows the same cleaned-up lines the log file holds. Folder paths are removed, leaving file names, on Windows and in the usual places on macOS and Linux (your home folder, external drives, /tmp and similar). A path that ends at a folder keeps that folder's own name, except your home folder itself (C:\Users\<name>, /Users/<name>, /home/<name>): its name is your account name, so it is hidden too. A Windows path that mixes \ and / is cleaned up as one path. A macOS or Linux path anywhere else is only cleaned up to its first space, unless that space is in its first folder (/Shared Drives/...), so folder names after a space can still show there; organize lines name only the file. When paths are hidden for a demo or recording (STRATOSORT_REDACT_PATHS=1), the panel also shows file names as "a file". This is best effort: it can hide some words that only look like file names (such as simple-main.js or a web address), it can show the part of a file name before its last space, and a name inside a web link or ending in .com, .co or .io can still show. The context column (which part of the app wrote the line) is never hidden.
    • Turning it on or off does not create a settings backup. While it is closed, nothing is collected for it.

11) Reporting Problems

Use the tester guide for full reporting instructions: Tester Guide

Direct bug form: Open a bug report


12) License

Personal and other noncommercial use is free under PolyForm Noncommercial 1.0.0. There is no trial, nothing expires, and no feature needs a key.

Commercial use (a company’s business, a paid product or service, or any use that is not a permitted noncommercial purpose) needs a paid license. See Commercial licensing or email contact@kennedyappliedsciences.com.