Two paths: hosted and self-hosted (one product)

One codebase, same Hub UI. Users choose how they run it.

The two paths

You do not need two separate products or two codebases. The same repo and UI support both. The only difference is which URL you open and which backend serves the API (our gateway + canister vs your Node Hub).

Hosted billing: Free plus paid tiers (Plus, Growth, Pro) with a monthly indexing token allowance visible in the Hub; token packs add rollover capacity; search is included under fair use. Billing is enforced in production. See HOSTED-CREDITS-DESIGN.md.

How it looks to users

On the landing (knowtation.store):

• "Open Knowtation Hub" → goes to knowtation.store/hub/ → hosted path. Sign in, use the Hub in the cloud. Optional: Connect GitHub for backup.
• "Run it yourself" or "Self-host" → goes to docs (e.g. GETTING-STARTED or a short Quick start (self-hosted) page): clone, set vault path + JWT secret, optionally OAuth, run npm run hub, open http://localhost:3333/.

So: one site, two clear choices. No switching code; we just document both and link accordingly.

Quick start (self-hosted)

Goal: Run the Hub locally with your own vault folder, optional semantic search, OAuth, and GitHub backup.

The same seven steps appear in the Hub UI under How to use (after you open the app). Below is the command-oriented version; keep them in sync.

1. Clone and install (skip git clone if you already have the repo — e.g. you develop Knowtation)

   git clone https://github.com/aaronrene/knowtation.git
   cd knowtation
   npm install
   cd hub && npm install && cd ..
   

2. Vault folder — Create a directory for notes (outside the repo is fine, e.g. ~/knowtation-vault):

   mkdir -p ~/knowtation-vault
   

3. Config — Copy config/local.example.yaml to config/local.yaml. Set the same absolute path as:

   • vault_path: in config/local.yaml
   • KNOWTATION_VAULT_PATH in .env at repo root
     For semantic search without Qdrant: vector_store: sqlite-vec, data_dir: data/, and embedding: (Ollama nomic-embed-text or OpenAI — see GETTING-STARTED.md §2). In .env also set HUB_JWT_SECRET (long random string).

4. Start the Hub

   npm run hub
   

   Open http://localhost:3333/ (use http://, not https://localhost).

5. Log in (OAuth) — OAuth client IDs/secrets do not ship with the repo. Register your own Google/GitHub OAuth app, add redirect URIs (e.g. http://localhost:3333/api/v1/auth/callback/google), put credentials in .env, restart the Hub. See hub/README.md.

6. Index (semantic search) — Listing notes works without this; Search vault needs an index:

   npm run index
   

   Or use Re-index in the Hub. After large imports, run again.

7. Import / automate / GitHub backup — Optional: import from other tools (CLI or capture); use the Hub for proposals and agents. For backup: How to use in the Hub → Step 7 (empty GitHub repo, git init in vault if needed, Connect GitHub, Back up now). Checklist: SELF-HOSTED-SETUP-CHECKLIST.md.

Full detail: GETTING-STARTED.md, setup.md. In-app walkthrough: open the Hub → How to use (links to these docs at the top).

Hosted path: GitHub backup (Connect GitHub, Back up now)

What we offer: On the hosted Hub you can connect your GitHub account so we push your vault (notes) to your repo. You don't run git yourself; you click Connect GitHub and Back up now in Settings.

What “git” does under the hood (we run it, not the user):

• Connect GitHub: OAuth to GitHub; we store a token (scope repo) and optionally the repo you want (e.g. owner/repo-name).
• Back up now: We fetch notes from the canister (GET /api/v1/export) and full proposals (list + one GET per id), then create a commit: Markdown files for each note plus .knowtation/backup/v1/snapshot.json (all proposal fields: status, review, enrich metadata, bodies). Push uses the GitHub API (blobs / tree / commit / ref), not a local git binary.

Storage and limits:

• Content: Vault = Markdown and small text files. No big binaries; no “file share” — just notes and metadata.
• GitHub free tier: 1 GB per repo (soft limit), 100 GB per account. For text/markdown, users are extremely unlikely to hit 1 GB. So: no big files, just text — and free tier is enough for normal use.
• If you ever exceed free tier: That’s a GitHub account limit (e.g. many repos or large repos). For a single “vault backup” repo with markdown, we don’t expect users to hit it. You can document: “Vault is markdown; well under GitHub’s free limits.”

Summary: One product, two paths (hosted + self-hosted). On hosted you can hook up GitHub so we commit and push your data to your repo; we use GitHub’s API, not raw git commands; storage is text-only and fits easily in GitHub’s free tier.