docs: record the separate data directory (ADR-0011)
Add ADR-0011: the community edition defaults to ~/.waggle-community, a temporary name that follows the product-name decision (Q8), and copies nothing from the commercial ~/.waggle. It supersedes point 4 of ADR-0009 and closes the pending "separate data directory" decision. Update the install guide, troubleshooting, capabilities, memory, architecture, the Windows build notes, THREAT_MODEL, README, .env.example and the changelog. Log UF-068 (Open): marketplace skills and plugins ignore a custom data directory.
This commit is contained in:
@@ -128,7 +128,8 @@ loads the `apps/web` build. The shell:
|
||||
|
||||
## Data
|
||||
|
||||
One data directory per user: `WAGGLE_DATA_DIR`, or `~/.waggle`. [install.md](install.md#where-your-data-lives)
|
||||
One data directory per user: `WAGGLE_DATA_DIR`, or `~/.waggle-community`, separate from the
|
||||
commercial edition's `~/.waggle` (ADR-0011). [install.md](install.md#where-your-data-lives)
|
||||
lists what it contains.
|
||||
|
||||
- **Memory** goes only through `MemoryStore` (`@waggle/memory-contract`). The shipped store keeps
|
||||
|
||||
@@ -34,7 +34,7 @@ set of skills for working with other people; it does not need team mode.
|
||||
|
||||
## Writing your own skill
|
||||
|
||||
A skill is a Markdown file in `<data>/skills/` (by default `~/.waggle/skills/`). Optional YAML
|
||||
A skill is a Markdown file in `<data>/skills/` (by default `~/.waggle-community/skills/`). Optional YAML
|
||||
frontmatter gives it a name and other metadata:
|
||||
|
||||
```markdown
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
# Troubleshooting
|
||||
|
||||
Common problems and what to do about them. Paths use `<data>` for the data directory:
|
||||
`~/.waggle` by default (`%USERPROFILE%\.waggle` on Windows), or `WAGGLE_DATA_DIR`.
|
||||
`~/.waggle-community` by default (`%USERPROFILE%\.waggle-community` on Windows), or
|
||||
`WAGGLE_DATA_DIR`.
|
||||
|
||||
## Installing
|
||||
|
||||
|
||||
@@ -87,7 +87,8 @@ sha256sum Waggle_<version>_amd64.deb
|
||||
|
||||
The window shows "Starting Waggle…" while the app starts its own server in the background. The
|
||||
server listens on `127.0.0.1` port 3333, or on another free port if 3333 is taken. Its log is in
|
||||
`~/.waggle/logs/service.log` (on Windows `%USERPROFILE%\.waggle\logs\service.log`).
|
||||
`~/.waggle-community/logs/service.log` (on Windows
|
||||
`%USERPROFILE%\.waggle-community\logs\service.log`).
|
||||
|
||||
### Update the desktop app
|
||||
|
||||
@@ -168,7 +169,7 @@ it. It listens on this computer only (`127.0.0.1`).
|
||||
|---|---|
|
||||
| `--port <number>`, `-p` | Use another port (default 3333) |
|
||||
| `--no-open` | Do not open the browser |
|
||||
| `--data-dir <path>` | Keep data in another directory (default `$WAGGLE_DATA_DIR` or `~/.waggle`) |
|
||||
| `--data-dir <path>` | Keep data in another directory (default `$WAGGLE_DATA_DIR` or `~/.waggle-community`) |
|
||||
| `--dir <path>` | Use a program directory other than the default |
|
||||
|
||||
If Waggle already runs on the port, `waggle-server` only opens the browser.
|
||||
@@ -244,9 +245,15 @@ send.
|
||||
|
||||
## Where your data lives
|
||||
|
||||
Both ways of installing use one data directory: `~/.waggle` (on Windows
|
||||
`%USERPROFILE%\.waggle`). Set `WAGGLE_DATA_DIR` to use another directory; the server installer
|
||||
also takes `--data-dir`.
|
||||
Both ways of installing use one data directory: `~/.waggle-community` (on Windows
|
||||
`%USERPROFILE%\.waggle-community`). Set `WAGGLE_DATA_DIR` to use another directory; the server
|
||||
installer also takes `--data-dir`.
|
||||
|
||||
The community edition does not touch `~/.waggle`, the data directory of the commercial Waggle,
|
||||
unless you point `WAGGLE_DATA_DIR` at it, so the two editions do not read or write each other's
|
||||
databases. Nothing is copied from
|
||||
`~/.waggle`: the community edition starts with an empty data directory. The directory name is
|
||||
temporary until the product name is decided.
|
||||
|
||||
| Path in the data directory | What it holds |
|
||||
|---|---|
|
||||
|
||||
@@ -77,7 +77,7 @@ A store reports what it can do, and the web UI hides what it cannot:
|
||||
|
||||
## Where mem0 keeps its data
|
||||
|
||||
Everything is in `memory/` inside the data directory (`~/.waggle/memory/` by default):
|
||||
Everything is in `memory/` inside the data directory (`~/.waggle-community/memory/` by default):
|
||||
|
||||
| File | Content |
|
||||
|---|---|
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# ADR-0009: The installer delivers a prebuilt server archive
|
||||
|
||||
- Status: Accepted
|
||||
- Status: Accepted; point 4 superseded by ADR-0011
|
||||
- Date: 2026-11-01
|
||||
|
||||
## Context
|
||||
|
||||
47
docs/oss/adr/0011-separate-data-directory.md
Normal file
47
docs/oss/adr/0011-separate-data-directory.md
Normal file
@@ -0,0 +1,47 @@
|
||||
# ADR-0011: The community edition has its own data directory
|
||||
|
||||
- Status: Accepted
|
||||
- Date: 2026-11-04
|
||||
- Supersedes: point 4 of ADR-0009
|
||||
|
||||
## Context
|
||||
|
||||
The community edition was made from the commercial Waggle and kept its default data directory,
|
||||
`~/.waggle` (`%USERPROFILE%\.waggle` on Windows). On a computer with both editions, the two
|
||||
would open the same `config.json`, vault, `waggle.db`, marketplace catalog, skills and logs. Their
|
||||
schemas and features have diverged: the community edition ignores the commercial keys in
|
||||
`config.json` (ADR-0001) and the commercial `.mind` memory files (ADR-0007), and the commercial
|
||||
edition does not know the mem0 store. Sharing one directory risks one edition changing data the
|
||||
other relies on.
|
||||
|
||||
## Decision
|
||||
|
||||
1. **The default data directory is `~/.waggle-community`** (`%USERPROFILE%\.waggle-community` on
|
||||
Windows) for the sidecar, the CLI, the marketplace, the desktop shell and the server
|
||||
installer. The project owner chose this on 2026-11-04.
|
||||
2. **`WAGGLE_DATA_DIR` still overrides the default** wherever it did before.
|
||||
3. **Nothing is migrated.** The community edition does not read, copy or move anything from
|
||||
`~/.waggle`. The owner explicitly does not want a migration: the product is still in
|
||||
development and nobody has data to bring over.
|
||||
4. **The name is temporary.** The final name follows the product-name decision (Q8). It is defined
|
||||
once per runtime so that the rename is one change in each:
|
||||
- TypeScript: `DEFAULT_DATA_DIR_NAME` and `DEFAULT_DATA_DIR_LABEL` in `@waggle/shared`, with
|
||||
`defaultDataDir()` in `@waggle/core` for Node code;
|
||||
- the Tauri shell: `DEFAULT_DATA_DIR_NAME` in `app/src-tauri/src/lib.rs`;
|
||||
- the server installer, which uses only Node's built-in modules: `DATA_DIR_NAME` in
|
||||
`packages/launcher/src/platform.ts`;
|
||||
- the marketplace, which installs on its own without the workspace packages:
|
||||
`DATA_DIR_NAME` in `packages/marketplace/src/data-dir.ts`.
|
||||
|
||||
`packages/shared/tests/data-dir.test.ts` fails when these copies differ. The CLI help text,
|
||||
which loads no dependency, spells the path out and `packages/cli/tests/cli-runtime.test.ts`
|
||||
checks it.
|
||||
|
||||
## Consequences
|
||||
|
||||
- A user who ran an earlier build of the community edition finds an empty data directory and
|
||||
sets Waggle up again.
|
||||
- The commercial keys stay untouched in `config.json` (ADR-0001), which still matters when a user
|
||||
points `WAGGLE_DATA_DIR` at `~/.waggle`.
|
||||
- The marketplace security scan flags skills that reference the skills folder of either
|
||||
directory.
|
||||
@@ -14,8 +14,9 @@ decision, add a new record that supersedes the old one.
|
||||
| [0006](0006-opt-in-analytics.md) | Analytics are opt-in | Accepted, one open item |
|
||||
| [0007](0007-memory-contract.md) | The memory contract and how it maps onto mem0 | Accepted |
|
||||
| [0008](0008-native-modules.md) | Native modules ship with a pinned Node runtime | Accepted |
|
||||
| [0009](0009-installer-server-archive.md) | The installer delivers a prebuilt server archive | Accepted |
|
||||
| [0009](0009-installer-server-archive.md) | The installer delivers a prebuilt server archive | Accepted, point 4 superseded by ADR-0011 |
|
||||
| [0010](0010-marketplace-catalog-in-repo.md) | The marketplace catalog stays in the repository | Accepted |
|
||||
| [0011](0011-separate-data-directory.md) | The community edition has its own data directory | Accepted |
|
||||
|
||||
## Pending decisions
|
||||
|
||||
@@ -28,5 +29,4 @@ work packages wait for the answer.
|
||||
| Product name and system identifiers | Temporary names | P1.3d, P2.6 |
|
||||
| Location of the public repository | `release.yml` is ready but has not run; the installer has no default download location (`--from`) | P2.6, P2.7 |
|
||||
| Installer signing | First release may ship unsigned with launch instructions | P2.5 |
|
||||
| Separate data directory from the commercial edition | Not separated yet | P1.3c |
|
||||
| PostHog project for the community edition | See ADR-0006 | P1.3a |
|
||||
|
||||
@@ -113,10 +113,10 @@ node scripts/release-smoke.mjs desktop --app "$env:LOCALAPPDATA\Waggle\waggle.ex
|
||||
2. Start Waggle from the Start menu. The window should move past "Starting Waggle…" to the
|
||||
Home screen.
|
||||
3. If it stays on "Starting Waggle…", close it and take the log from
|
||||
`%USERPROFILE%\.waggle\logs\service.log`.
|
||||
`%USERPROFILE%\.waggle-community\logs\service.log`.
|
||||
4. Chat needs a model: an API key in Settings → Models (Provider Keys), or a running Ollama.
|
||||
|
||||
Waggle keeps its data in `%USERPROFILE%\.waggle`.
|
||||
Waggle keeps its data in `%USERPROFILE%\.waggle-community`.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
|
||||
@@ -329,7 +329,7 @@ npx tsx packages/memory-mem0/bench/search-quality.ts --engines mem0,cosine
|
||||
npx tsx packages/memory-mem0/bench/search-quality.ts --out /tmp/search-quality.json
|
||||
```
|
||||
|
||||
The in-process model must be in `~/.waggle/models` (the sidecar downloads it on first start)
|
||||
The in-process model must be in `~/.waggle-community/models` (the sidecar downloads it on first start)
|
||||
or in the directory named by `WAGGLE_MODELS_DIR`; the bench refuses network access and does
|
||||
not download it.
|
||||
|
||||
|
||||
@@ -96,6 +96,7 @@ Baseline: commit `b20b138` of the main Waggle repository.
|
||||
| UF-065 | The Windows uninstaller names a "Data & Privacy" settings page that does not exist | Fixed | Desktop, Windows installer |
|
||||
| UF-066 | Installed builds have no capability packs and no starter skills | Fixed | Sidecar bundle, SDK |
|
||||
| UF-067 | The status bar names a default model that chats cannot use | Fixed | Sidecar, Web UI |
|
||||
| UF-068 | Marketplace skills and plugins ignore the configured data directory | Open | Marketplace, sidecar |
|
||||
|
||||
## Entries
|
||||
|
||||
@@ -675,3 +676,12 @@ Entries UF-010 to UF-019 come from the UI audit `anti-slop/audit-001-2026-10-14.
|
||||
- Cause: the chat route resolves the configured model to a usable one (`resolveUsableModel`), but the status endpoint returns the configured model as is.
|
||||
- What we did: the status endpoint resolves the model the same way, without changing the configured one. A test covers it.
|
||||
- Recommendation: same change in the main project.
|
||||
|
||||
### UF-068. Marketplace skills and plugins ignore the configured data directory
|
||||
- Status: Open
|
||||
- Found: 2026-11-04
|
||||
- Where: at commit `b20b138`, `packages/marketplace/src/installer.ts:47-50` (`SKILLS_DIR`, `PLUGINS_DIR`, `REGISTRY_PATH`); the sidecar reads `<dataDir>/skills` and `<dataDir>/plugins` (`packages/server/src/local/routes/skills.ts:43`)
|
||||
- Symptom: with `WAGGLE_DATA_DIR` or a custom data directory, a skill or plugin installed from the Marketplace is written to the default directory in the home folder, so the sidecar does not list or load it.
|
||||
- Cause: the installer builds these paths from `os.homedir()` when its module loads. Only `.mcp.json` honors `WAGGLE_DATA_DIR`, and the MCP route also saves the entry in the server's data directory to make up for it.
|
||||
- What we did: nothing yet. The community edition changed the default directory name only (ADR-0011).
|
||||
- Recommendation: pass the server's data directory to `MarketplaceInstaller`, or resolve the paths at call time from `WAGGLE_DATA_DIR` like `mcpConfigPath()`.
|
||||
|
||||
Reference in New Issue
Block a user