README.md

layout	single
title	Developer Docs Index
sidebar	nav docs

Pick the doc that matches what you need to do.

I am new here

Start with ONBOARDING.md — clone-to-first-PR in ~30 minutes. Covers the mental model, the five files to read first, an end-to-end IPC trace, the service inventory, and the surprises that bite senior devs.

Then keep these tabs open:

Doc	What it answers
GETTING_STARTED.md	"What are the mechanical setup steps?"
GLOSSARY.md	"What does this term mean in this codebase?"
PHILOSOPHY.md	"What design principles guide this codebase?"
PACKAGE_SCRIPTS.md	"Which npm run do I want?"
DEBUGGING_GUIDE.md	"My local dev is broken — what now?"
ARCHITECTURE.md	"How are main / preload / renderer wired?"
IPC_CONTRACTS.md	"What's the wire format for channel X?"
DI_PATTERNS.md	"How do I register/resolve a service?"
ERROR_HANDLING_GUIDE.md	"What error type / classifier should I use?"
CODE_QUALITY_STANDARDS.md	"What does this project consider 'clean code'?"
TESTING.md	"How do I write/run tests for this change?"
CONFIG.md	"Which STRATOSORT_* env var controls X?"

Licensing

Doc	What it is
LICENSE (repo root)	Live grant: PolyForm Noncommercial 1.0.0 (personal/noncommercial free)
COMMERCIAL.md	How to buy a commercial license
COMMERCIAL_COMPLIANCE.md	Pre-release third-party license audit + appendices

Privacy and network

Doc	What it answers
NETWORK_TRANSPARENCY.md	Every network call the shipped app can make
AI_PROVIDERS.md	Optional BYOK cloud routing
MCP_SERVER.md	Local MCP server for other AI tools

I am running a release

Doc	What it covers
RELEASING.md	Tagging, pre-flight, post-install smoke, signing/notarize
MAC_SIGNING.md	macOS Developer ID signing + notarization runbook
COMMERCIAL_COMPLIANCE.md	Pre-release license audit + appendices
THIRD_PARTY_NOTICES.md	Attribution shipped in the installer (load-bearing)
UPDATE_HOST.md	electron-updater feed configuration

I am working on a specific subsystem

Subsystem	Doc
Search / Knowledge OS	FEATURES_GRAPH.md, SEMANTIC_PIPELINE.md, ORAMA_VECTOR_SIDECAR.md
UI animation	MOTION_SYSTEM.md
AI provider plumbing (BYOK)	AI_PROVIDERS.md
MCP server	MCP_SERVER.md
Cross-package import discipline	DEPENDENCY_BOUNDARIES.md

I am a tester or end user

These docs are for non-developer audiences. Skip them if you're working on the code.

Doc	Audience
USER_GUIDE.md	End user — how the app behaves
E2E_WALKTHROUGH.md	Visual tour (stills + how-to clip)
INSTALL_GUIDE.md	Installer for any user
BETA_TESTER_GUIDE.md	Tester — install, checklist, bug reports
walkthrough-assets/HOW_TO_USE_TOUR.md	How to regenerate the recorded clip (npm run tour:record)

Everything above is live. Tour media: walkthrough-assets/HOW_TO_USE_TOUR.md, how-to-use.mp4, shorts/stratosort-short.mp4, and demo-files/. Public stills for Pages live in assets/e2e-screenshots/.

Load-bearing files that must stay: THIRD_PARTY_NOTICES.md, commercial-use-inventory.json, commercial-model-licenses.json, commercial-compliance-waivers.json. They are in git; Pages does not publish the JSON inventories.

Gitignored (local only): walkthrough-assets/tour-raw/, walkthrough-assets/tour/ (recorder PNG dumps), walkthrough-assets/shorts/probe/, walkthrough-assets/lessons/probe/, .legacy/, licenses-production.json.

What's in the repo root (not under docs/)

File	Purpose
README.md	Public-facing project overview
CLAUDE.md	Project intelligence for AI assistants
CONTRIBUTING.md	How to contribute
CODE_OF_CONDUCT.md	Community standards
SECURITY.md	How to report vulnerabilities
PRIVACY.md	Data-handling policy
CHANGELOG.md	Release notes
LICENSE	PolyForm Noncommercial 1.0.0 (commercial sold separately)

Adding a new doc

1. Name it UPPERCASE_WITH_UNDERSCORES.md.
2. Put a one-line description at the top so the index entry has something to copy.
3. Add a row to the table in the matching section above.
4. If the doc is regenerable from code (e.g. line-by-line audits), do not check it into docs/. Add a regen script under scripts/ and let people run it on demand.