codesynapt 0.0.0

package/LICENSES.md

@@ -0,0 +1,141 @@
+# Licensing overview
+
+CodeSynapt uses **dual licensing**. This document explains what that
+means in plain language. For the actual legal text, see:
+
+- **[LICENSE](./LICENSE)** — GNU Affero General Public License v3.0 (main app)
+- **[plugin-api/LICENSE](./plugin-api/LICENSE)** — MIT (plugin API)
+
+## The short version
+
+| Part of the project | License | What you can do |
+|---|---|---|
+| **Main app** — everything outside `plugin-api/` | **AGPL-3.0** | Free for any use; if you modify it and offer it as a network service, you must share your source under AGPL too |
+| **Plugin API** — everything inside `plugin-api/` | **MIT** | Use, modify, distribute, sell — under any license you choose |
+
+## What you can do without asking (AGPL-3.0)
+
+- **Personal use** — run it on your own computer for any reason
+- **Internal use within a business or organization** — use CodeSynapt
+  to analyze your own or your employer's codebases. Running it internally
+  for your team does NOT trigger AGPL's network-share clause.
+- **Academic, educational, research use**
+- **Inspection and learning** — read the code, copy snippets
+- **Forks for personal modification** — make your own private variant
+- **Build plugins under any license** — including proprietary, including selling them (plugin API is MIT)
+
+## When does AGPL apply?
+
+AGPL-3.0's copyleft kicks in when **you offer a modified version to others
+over a network**:
+
+- Modified CodeSynapt running as a **hosted SaaS** that other people sign up for? → You must publish your modified source under AGPL.
+- Modified CodeSynapt **bundled into a closed-source product** you distribute? → Same — derived work must be AGPL.
+- Modified CodeSynapt running **only inside your company**, used by your own employees? → AGPL does NOT require disclosure. Internal use is free.
+- **Unmodified** CodeSynapt as part of your workflow? → No obligations beyond keeping the LICENSE file with it.
+
+This is the same model used by Plausible Analytics, Cal.com, MongoDB
+Compass, and many other modern OSS projects.
+
+## What a commercial license unlocks
+
+If AGPL's copyleft is incompatible with your use case (e.g. you want
+to ship a modified version in a closed-source SaaS, or embed CodeSynapt
+inside a proprietary product), a **commercial license** lifts those
+obligations.
+
+Pricing scales with deployment size and revenue:
+
+| Tier | Who | Typical pricing |
+|---|---|---|
+| **Open Source** | Anyone OK with AGPL | Free |
+| **Starter** | Individuals / sub-$100k annual revenue | Contact for quote |
+| **Growth** | $100k–$1M annual revenue | Per-developer or revenue-based |
+| **Enterprise** | $1M+ annual revenue | Negotiated (revenue %, support SLA, etc.) |
+
+For commercial licensing inquiries, open a GitHub Discussion or contact:
+**wing1008** on GitHub (DM via issues or use the contact form linked
+from the project README).
+
+## What is NOT commercial use
+
+These are commonly mistaken but are actually fine under AGPL-3.0
+without a commercial license:
+
+- Your company uses CodeSynapt internally to analyze its codebase ✅
+- You're a freelancer running CodeSynapt while working on a client project ✅
+- You ship CodeSynapt **unmodified** as part of a developer workflow ✅
+- You publish a tutorial / book / video using CodeSynapt ✅
+- You contribute back upstream improvements ✅ (this is what AGPL encourages)
+
+## Plugin API (MIT)
+
+Everything inside `plugin-api/` is **MIT-licensed**. This means:
+
+- Build plugins under any license (including proprietary, including selling them)
+- Fork the plugin API
+- Embed plugin API types in your own tools
+- The MIT boundary is intentional — we want a thriving plugin ecosystem
+  without AGPL "viral" concerns
+
+## Why dual-licensed?
+
+CodeSynapt is built and maintained by **one person in their spare time**
+(wing1008). The dual model balances three goals:
+
+1. **Freedom to use** — anyone can use CodeSynapt for any purpose
+2. **Sustainability** — companies building businesses on top of CodeSynapt
+   contribute back, either as code (AGPL) or as a commercial license fee
+3. **Plugin ecosystem** — plugin authors aren't constrained by AGPL
+
+This is the same approach used by:
+
+- **MariaDB** (GPL + Commercial)
+- **MySQL** (GPL + Commercial)
+- **Plausible Analytics** (AGPL + Enterprise)
+- **Cal.com** (AGPL + Enterprise)
+- **Sourcegraph** (AGPL + Enterprise)
+
+## Third-party dependencies
+
+CodeSynapt bundles several open-source dependencies, all under
+permissive licenses (MIT, Apache-2.0, BSD, ISC). The complete list
+is verifiable via:
+
+```sh
+npm run license-check
+```
+
+Key dependencies:
+
+| Package | License |
+|---|---|
+| `@babel/parser`, `@babel/traverse` | MIT |
+| `chokidar` | MIT |
+| `three` | MIT |
+| `ws` | MIT |
+| `electron` | MIT |
+| `electron-builder` | MIT |
+| `electron-updater` | MIT |
+| `@electron/fuses` | MIT |
+
+### Bundled runtime (Windows installer only)
+
+The Windows `.exe` installer bundles a copy of Node.js 22 LTS (the
+`node.exe` binary, ~76 MB) as an optional install component. If your
+system already has Node.js installed, the installer auto-detects it
+and skips the bundle to save disk space.
+
+| Bundled binary | Version | License | Source |
+|---|---|---|---|
+| Node.js | 22.11.0 LTS (Jod) | MIT | <https://nodejs.org/dist/v22.11.0/> |
+
+Node.js is itself a project bundling many components (V8, libuv,
+OpenSSL, etc.) — each with their own permissive license. Full
+attribution: <https://github.com/nodejs/node/blob/main/LICENSE>.
+
+## Questions
+
+If you're unsure whether your use case requires a commercial license,
+open a GitHub Discussion and we'll help clarify. **There are no
+gotchas — internal company use is always free under AGPL-3.0.**

package/README.md

@@ -0,0 +1,331 @@
+# CodeSynapt
+
+[![CI](https://img.shields.io/github/actions/workflow/status/wing1008/codesynapt/ci.yml?branch=main&label=ci)](https://github.com/wing1008/codesynapt/actions/workflows/ci.yml)
+[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL%203.0-blue.svg)](./LICENSE)
+[![Commercial license available](https://img.shields.io/badge/Commercial-Available-orange.svg)](./LICENSES.md)
+[![Plugin API: MIT](https://img.shields.io/badge/Plugin%20API-MIT-green.svg)](./plugin-api/LICENSE)
+[![Version](https://img.shields.io/github/package-json/v/wing1008/codesynapt?label=version&color=informational)](./CHANGELOG.md)
+[![Node 20|22](https://img.shields.io/badge/Node-20%20%7C%2022-339933?logo=node.js&logoColor=white)](./package.json)
+[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey)](./docs/installation.md)
+[![Tests](https://img.shields.io/badge/tests-100%20passing-brightgreen)](./tests/)
+[![GitHub Sponsors](https://img.shields.io/github/sponsors/wing1008?label=Sponsor&logo=GitHub&style=social)](https://github.com/sponsors/wing1008)
+[![Buy me a coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-FFDD00?logo=buymeacoffee&logoColor=black)](https://buymeacoffee.com/wing1008)
+
+> **MCP-native code graph for AI agents — see blast radius live.**
+> The dependency map Claude Code / Cursor / any MCP agent should be
+> reading before it edits your code. Live-updating (~300 ms after a
+> save), no re-indexing, no cloud. Same scanner ships as MCP server
+> (8 intent-shaped tools), CLI (`cs`), and a 3D desktop window that
+> pulses every node the AI touches.
+
+## Why this exists
+
+Coding agents (Claude Code, Cursor, Aider…) read files one at a time.
+They have no project-wide map: which files matter, what imports what,
+which routes match which fetch calls, what external services the code
+talks to, which "v2" file is the real one vs. abandoned drafts.
+
+`codesynapt` builds that map and exposes it three ways:
+
+| Surface | For | Example |
+|---|---|---|
+| **MCP server** | AI coding agents | "Which files import `auth.js`?" → agent calls `cs_query({action:'users', id:'auth.js'})` |
+| **CLI** (`cs`) | terminal users, scripts, CI | `cs external` — list every API/website your code talks to; `cs ci-diff main..HEAD` — PR blast radius as Markdown |
+| **Desktop app** | visual exploration | drop folder → 3D graph with live updates; watch the AI navigate live |
+
+All three share the same scanner: imports across JS/TS, Python, Go, Rust, Java/Kotlin, C/C++, C#, Swift, Dart, Ruby, PHP (plus Vue/Svelte components), route↔fetch matching for full-stack monorepos, external URL inventory, and dynamic-pattern detection.
+
+## What it does well
+
+- **8 intent-shaped MCP tools** (not 37 narrow ones) — `cs_summary`, `cs_query`, `cs_blast`, `cs_intent`, `cs_health`, `cs_change`, `cs_trace`, `cs_ui`. Each takes an `action` enum. Designed so the agent picks the right one with a glance, not by scanning a wall of tool names.
+- **AI-aware response envelope** — every response includes `meta: { scannedAt, tokenEstimate, totalAvailable, truncated }`. The agent budgets tokens before drilling deeper.
+- **Blast radius before edit** — `cs_blast({action:'safety', id})` returns 🟢/🟡/🔴 verdict + reasons in one call; `action:'bundle'` packs the closest neighbours into a token budget so the agent reads the right context first.
+- **Verified dependency accuracy** — import resolution is checked against independent ground truth (TypeScript Compiler API, Python `ast`, language-native rules) at precision/recall ≈ 1.0 across 11 languages on real codebases (VS Code ~6.8k files; Django), measured on library/app source (tests/generated code excluded). For Go, C# and Swift the edge is module/namespace-level (one import links the importing file to the imported unit). Honest limit: it follows *static imports*, so it does **not** see autoload / DI / reflection-implicit dependencies (Rails/Zeitwerk, Spring) — those carry no import statement to resolve, and are surfaced as `caveat` markers rather than silently dropped.
+- **Live updates ~300 ms** — chokidar file-watcher + 60 ms snapshot debounce. No re-indexing, no manual refresh, no cloud round-trip. (Most code-intelligence tools require an explicit re-index step — this one doesn't.)
+- **Live agent visualization** — when the desktop window is open, every MCP call pulses the touched node in 3D. You see the AI navigate.
+- **Full-stack route↔fetch matching** — JS/TS, Python, Next.js file-system API routes auto-detected. Frontend `fetch('/api/billing')` linked to `app/api/billing/route.ts` automatically.
+- **Headless + CI** — `cs scan`, `cs serve`, `cs ci-diff main..HEAD`, `cs ci-gate --max-blast 50`. No Electron required for CI / SSH / Docker.
+- **Auto-history per file** (opt-in) — every save snapshots previous content (cap 3). Roll back via `cs_change({action:'restore'})`.
+- **External URL inventory** — `cs_intent({action:'external'})` lists every API host the project calls (Stripe, OpenAI, your own backend…), grouped by domain.
+- **Env / secret leak detection** — `cs_health({action:'secrets'})` flags server-only env vars accidentally used in client bundles.
+- **Offline by design** — no network calls, no telemetry, no cloud sync. The whole graph lives in memory + your local `.codesynapt/` directory.
+- **i18n** — Korean ↔ English toggle, persists.
+
+## Quick start
+
+Three install paths, pick the one that matches you.
+
+### Path 1 — Windows `.exe` (easiest, no Node required up-front)
+
+Download `CodeSynapt-Setup-<version>.exe` from the [Releases](https://github.com/wing1008/codesynapt/releases) page. Run the installer:
+
+- **Auto-detects** existing Node.js. If found, uses your system Node (saves 76 MB). If not, ships Node 22 LTS bundled.
+- Adds `cs` / `codesynapt` / `codesynapt-mcp` to your user `PATH` automatically (toggle "Add cs command to PATH" — checked by default).
+- Installs to `%LOCALAPPDATA%\Programs\CodeSynapt\`. **Updates are clean**: installing a newer `.exe` auto-removes the old one and preserves your data under `%APPDATA%\codesynapt\`.
+
+After install, open **a new** PowerShell:
+
+```sh
+cs --help
+```
+
+If `cs` shows usage, you're done. (Unsigned installer — Windows SmartScreen will warn "unverified publisher"; click "More info → Run anyway".)
+
+### Path 2 — Developer / source (any OS)
+
+```sh
+git clone https://github.com/wing1008/codesynapt.git
+cd codesynapt
+npm install                      # full install — desktop + CLI + MCP (~700 MB w/ Electron)
+npm link                         # adds cs / codesynapt / codesynapt-mcp to your PATH
+npm start                        # desktop app + HTTP control API on :7707
+```
+
+### Path 3 — CLI / MCP only (no desktop, no 3D — for CI / SSH / Docker, ~30 MB)
+
+```sh
+git clone https://github.com/wing1008/codesynapt.git
+cd codesynapt
+npm install --omit=optional --omit=dev
+npm link
+cs scan .                        # one-shot
+cs serve .                       # long-running HTTP daemon (no Electron)
+```
+
+`three` (3D renderer) and `ws` are `optionalDependencies`; `electron` is a devDependency. CI runners can skip the 700 MB Electron download entirely.
+
+### CLI — `cs` command
+
+After `.exe` install (Path 1) or `npm link` (Paths 2/3), the `cs` command is on your PATH. The Node `codesynapt` and `codesynapt-mcp` aliases also work.
+
+#### Headless — no desktop window needed (CI / SSH / Docker)
+
+```sh
+cs scan [path] --summary               # one-shot project overview
+cs scan [path] --json                  # full graph as JSON
+cs serve [path] --port 7707            # long-running HTTP API daemon
+cs ci-diff main..HEAD                  # PR impact report (Markdown by default)
+cs ci-gate main..HEAD --max-blast 50   # CI gate, exits 1 on breach
+```
+
+#### Connected — talks to a running desktop or `cs serve` daemon at :7707
+
+```sh
+# Setup
+cs ensure                              # ensure desktop is running with cwd loaded
+                                       # (auto-launches if dead, swaps folder if needed, no-op otherwise)
+cs init                                # one-time setup: CLAUDE.md + /codesynapt slash + mcp add hint
+
+# Most useful first:
+cs summary                             # cheap project overview (Layer 1)
+cs safety src/x.ts                     # 🟢/🟡/🔴 + one-line advice
+cs bundle src/x.ts --budget 8000       # pack neighbours into token budget
+cs blast  src/x.ts 3                   # transitive dependents + token estimate
+cs suggest                             # "what to ask the AI next" recommendations
+cs preflight                           # deploy-readiness check
+cs env [VAR]                           # .env declared vs used
+cs secrets                             # server-only env leaked to client?
+cs feature payment                     # keyword → FE/BE/shared cluster
+cs url /billing                        # URL → file (Next.js/Astro/SvelteKit)
+cs schema [Model]                      # DB models (Prisma/Drizzle/SQLAlchemy)
+cs external                            # external APIs/websites by domain
+cs deps  src/x.ts                      # what does x.ts import?
+cs users src/x.ts                      # who imports x.ts?
+cs find  auth                          # substring search across **file ids only** (path match)
+cs search "RUNPOD_API_KEY"             # full-text **content** search (mtime LRU cache, sub-50ms when warm) — best-effort
+cs ls    --limit 10                    # top 10 most-imported files
+cs focus src/x.ts                      # move desktop camera (desktop only)
+```
+
+> **`cs search` caveat**: full-text search is *best-effort*. If invoked while the initial scan is still running, the endpoint returns `503 scan in progress` — retry after a couple of seconds. Under heavy event-loop pressure (large repo + fresh scan), a single search can occasionally hang; this is a known limitation tracked for future `worker_threads` refactor. `cs_query({action:'search'})` MCP returns the same payload; AI agents automatically fall back to Read+Grep on failure.
+
+The desktop app exposes ~30 endpoints. Run `cs --help` for the full
+list including history, restore, refresh, tour, timeline, trace.
+
+> Used `git clone` (Paths 2/3) and the `cs` command isn't found? Run `npm link` inside the cloned repo — it registers `cs` / `codesynapt` / `codesynapt-mcp` / `codesynapt-server` globally.
+
+## Hook up your AI agent
+
+### Claude Code — recommended setup (2 commands)
+
+```sh
+cd <your-project>
+cs init                              # generates CLAUDE.md + installs /codesynapt slash commands
+claude mcp add codesynapt codesynapt-mcp   # registers 8 cs_* tools (one-time, per OS user)
+```
+
+That's it. Inside any Claude Code session in that project:
+
+```
+/codesynapt        ← FORCE mode: cs_* preferred for every non-trivial query/edit
+/codesynapt-auto   ← AUTO mode:  cs_* only for non-trivial work (skips typos/docs)
+```
+
+**Default is OFF** — `cs_*` tools are not called until you enter a mode. `/clear` or new session resets to OFF.
+
+The slash command's first step is `cs ensure` — it guarantees the desktop is running and the **current working directory is loaded**. Auto-launches the desktop if dead, swaps folder if a different one was loaded, no-op otherwise. One command, zero clicks.
+
+### Manual MCP registration (any client)
+
+If you skipped `cs init` or use Cursor/Continue/Cline:
+
+```sh
+claude mcp add codesynapt node /absolute/path/to/codesynapt/packages/core/bin/codesynapt-mcp.cjs
+```
+
+That registers 8 intent-shaped MCP tools (all `cs_*`). In any
+session, just ask project-shape questions and Claude picks the right
+action automatically:
+
+> *"이 프로젝트가 호출하는 외부 API 다 알려줘"*
+> → `cs_intent({action:'external'})` → domains grouped by file caller
+
+> *"`src/auth/session.ts` 수정하면 어떤 파일들이 영향받아?"*
+> → `cs_blast({action:'safety', id:'src/auth/session.ts'})` → 🟡 CAUTION, 23 dependents, advice
+
+> *"수정 전에 같이 봐야 할 파일 묶음 만들어줘"*
+> → `cs_blast({action:'bundle', id, budget:8000})` → packed files within token budget
+
+> *"import 안 되는 잔재 파일 찾아줘"*
+> → `cs_health({action:'legacy'})` → orphan/path/filename/duplicate candidates with confidence
+
+> *"`/billing` 화면이 어느 파일이야?"*
+> → `cs_intent({action:'url', path:'/billing'})` → matched file (Next.js / Astro / SvelteKit aware)
+
+> *"src/api/payment.ts 한 시간 전 버전으로 되돌려"*
+> → `cs_change({action:'history', id})` → `cs_change({action:'restore', id, ts})`
+
+> *"배포해도 안전한가?"*
+> → `cs_health({action:'preflight'})` → undeclared env / http URLs / hub tests / leaks — overall ok|warn|fail
+
+If the desktop app is open you'll **see** every tool call pulse the
+relevant node in 3D — a live X-ray of what the agent is doing.
+
+### Cursor / Continue / Cline / others
+
+Same MCP server. Standard config — see [**docs/mcp-setup.md**](./docs/mcp-setup.md) for examples.
+
+## Use cases
+
+**1. AI-assisted refactoring without breakage.** Before changing
+`src/lib/payment.ts`, ask Claude "is it safe to refactor?". Agent runs
+`cs_blast({action:'safety'})` → 🟢/🟡/🔴 with reasons in one call.
+Follow up with `action:'bundle'` to get the closest neighbours packed
+into a token budget — the right context for the edit.
+
+**2. CI gate for impact-risky PRs.** Add one line to your CI:
+`cs ci-gate main..HEAD --max-blast 50` fails the build if a single
+file changes touches >50 dependents. Or `cs ci-diff main..HEAD
+--format=github-comment` to post a Markdown impact report on the PR.
+
+**3. External API + secret audit.** `cs_intent({action:'external'})`
+lists every external host (Stripe, OpenAI…), grouped by caller — for
+security review, migration planning, API spend estimation.
+`cs_health({action:'secrets'})` catches server-only env vars
+accidentally used in client bundles.
+
+**4. Cleaning up "v2" / dead files.**
+`cs_health({action:'legacy'})` returns confidence-scored cleanup
+candidates across 4 categories (orphan / path / filename / duplicate),
+so you know which version is the real one before deleting.
+
+**5. Full-stack route tracing.** codesynapt matches `fetch('/api/x')`
+client calls to `app.get('/api/x', …)` server routes across JS/TS and
+Python (Express, Fastify, Koa, Hono, Flask, FastAPI) — plus Next.js
+file-system API routes (`app/api/*/route.ts`, `pages/api/*`)
+auto-detected. The graph shows client→server lines so the AI can
+answer "which UI calls this endpoint?"
+
+**6. Watching the AI think.** Open the desktop app, start a Claude
+Code session in your terminal, ask the agent to do something
+non-trivial. The graph pulses every file the agent inspects + draws
+a trail through its navigation path. The AI trace panel logs each
+tool call live.
+
+**7. URL → file in one query.** Designer says "the /billing screen
+looks broken". `cs_intent({action:'url', path:'/billing'})` →
+`src/app/(dashboard)/billing/page.tsx` (Next.js route groups + dynamic
+segments handled).
+
+**8. Onboarding a new project.** Open it in codesynapt, hit the 🧭
+**Tour** button. The camera flies through entry points, top hubs, and
+external API integration spots. Or ask Claude: "give me the guided
+tour" → `cs_trace({action:'tour'})`.
+
+**7. Watching project evolution.** Hit the ⏱ **Time-lapse** button.
+The slider scrubs through git history — files appear at their first
+commit. Press play to watch the project grow over 25 seconds. Pairs
+well with screen recordings for `r/dataisbeautiful`.
+
+**8. Recovering AI-edited files.** Turn on **Auto history** in
+Settings. Every save (yours or the AI's) snapshots the previous
+version. Roll back from the inspector if Claude edits the wrong
+thing.
+
+## Desktop app — visual surface
+
+![screenshot placeholder — add screenshot.png here]
+
+Built on Electron + Three.js. Scales to 100k+ files. Features:
+
+- **Real-time** — drop a folder, watch the graph form in seconds; live updates as you edit
+- **Scales** — 300k node smoke test runs at 50fps active / 100fps idle
+- **Spherical force-directed layout** with cursor-anchored zoom (zoom-in tracks cursor; zoom-out drifts toward center like Obsidian)
+- **Live AI agent visualization** — pulse + ripple + cyan-to-magenta navigation trail when MCP calls hit the graph
+- **Idle auto-rotate camera** + scene heartbeat for the "alive" feel; instantly stops on user input
+- **Inspector** with full-file editor + auto-save + connection badge + history panel + diff view
+- **Auto file history** — opt-in, max 3 versions per file under `.codesynapt/history/`
+- **Changes panel** (📝) — every file the session has modified, with one-click line-diff
+- **Onboarding tour** (🧭) — auto-generated walkthrough of entry points + hubs + API integration
+- **Time-lapse** (⏱) — slider replays git history; files appear at their first commit
+- **i18n** — Korean ↔ English toggle, persisted
+- **7 themes** — Observatory, Minimal, Terminal, Maximal, Carbon (CRT), Mono (Tokyo Night), Daylight
+- **Extensible** — plugin API for themes, exporters, parsers, layouts, panels, and context actions
+- **Cross-platform** — macOS (Intel + Apple Silicon), Windows, Linux
+- **Private by design** — local-only HTTP control API on 127.0.0.1, no telemetry, code never leaves your machine
+
+For OS-specific installation notes, see **[docs/installation.md](./docs/installation.md)**.
+
+## Documentation
+
+| Looking for… | Read |
+|---|---|
+| **MCP setup for Claude Code / Cursor / Continue** | [**docs/mcp-setup.md**](./docs/mcp-setup.md) |
+| How to install on your OS | [docs/installation.md](./docs/installation.md) |
+| Features and what it does | [docs/features.md](./docs/features.md) |
+| Keyboard / mouse controls | [docs/controls.md](./docs/controls.md) |
+| How the internals work | [docs/architecture.md](./docs/architecture.md) |
+| Building a plugin or theme | [plugin-api/README.md](./plugin-api/README.md) |
+| What changed in each release | [CHANGELOG.md](./CHANGELOG.md) |
+| Reporting a security issue | [SECURITY.md](./SECURITY.md) |
+| Getting help or asking questions | [.github/SUPPORT.md](./.github/SUPPORT.md) |
+| Contributing code | [CONTRIBUTING.md](./CONTRIBUTING.md) |
+| Community guidelines | [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) |
+| AI coding agent guide (working ON codesynapt) | [AGENTS.md](./AGENTS.md) |
+
+## License
+
+CodeSynapt uses **dual licensing**:
+
+- **Main app** ([LICENSE](./LICENSE)): **[AGPL-3.0-or-later](https://www.gnu.org/licenses/agpl-3.0.en.html)**
+  - ✅ Free for personal, internal company, academic, and research use
+  - ✅ Free to inspect, modify, and build plugins
+  - ⚠️ If you modify CodeSynapt and offer it to others as a network service, your modifications must also be open-sourced under AGPL
+  - 💼 **Commercial license available** for organizations that can't accept AGPL — see [LICENSES.md](./LICENSES.md)
+- **Plugin API** ([plugin-api/LICENSE](./plugin-api/LICENSE)): **MIT**
+  - Build and distribute plugins under any license you choose
+
+For commercial licensing inquiries, open a [GitHub Discussion](https://github.com/wing1008/codesynapt/discussions) or DM `@wing1008`.
+
+For a plain-language explanation of the licensing model, see **[LICENSES.md](./LICENSES.md)**.
+
+## Support the project
+
+CodeSynapt is built by one person ([@wing1008](https://github.com/wing1008)) in their spare time. If it saves you time, consider:
+
+- ⭐ **Star the repo** — costs nothing, helps a lot
+- 💚 **[GitHub Sponsors](https://github.com/sponsors/wing1008)** — recurring or one-time
+- ☕ **[Buy me a coffee](https://buymeacoffee.com/wing1008)** — one-time tip
+- 🏢 **[Commercial license](./LICENSES.md)** — if your company needs to ship CodeSynapt without AGPL obligations
+
+Contributions in the form of bug reports, PRs, and docs improvements are also very welcome — see **[CONTRIBUTING.md](./CONTRIBUTING.md)**.