@cairnkeep/cli 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable user-facing changes are documented here. This project follows
+[Semantic Versioning](https://semver.org/).
+
+## [1.1.2] - 2026-07-14
+
+### Added
+
+- Define a provider-neutral managed-distribution contract for private overlays.
+- Ship a versioned overlay manifest schema and local-first example.
+- Document wrapper commands, profile locks, data-routing diagnostics, private
+  registry delivery, package hygiene, fleet migration, and rollback practices.
+
+## [1.1.1] - 2026-07-14
+
+### Fixed
+
+- Ship and resolve the default document-RAG sync helper from the npm package,
+  with user-owned XDG config/state paths and legacy-path compatibility.
+- Make repository CI install locked root dependencies before running checks.
+- Make the clean macOS bootstrap test create its target directory explicitly.
+
+### Changed
+
+- Add release-to-npm automation with provenance, tarball, and SBOM artifacts.
+- Document supported clients, platforms, storage placement, and optional data
+  flows more explicitly.
+- Add community contribution, support, and conduct templates.
+
+## [1.1.0] - 2026-07-13
+
+### Added
+
+- Add authenticated remote HTTP memory with stable per-project session routing.
+- Add explicit client routing headers for scopes and document-RAG workspaces.
+- Document local, remote, export, backup, and bearer-token deployment models.
+
+## [1.0.5] - 2026-07-13
+
+### Fixed
+
+- Make the npm tarball install self-contained and verify it on clean systems.
+- Preserve executable permissions and Bash 3.2 portability on macOS.
+- Add backup-first uninstall and SQLite-safe memory export/import guidance.
+
+[1.1.1]: https://github.com/cairnkeep/cairnkeep/compare/v1.1.0...v1.1.1
+[1.1.0]: https://github.com/cairnkeep/cairnkeep/compare/v1.0.5...v1.1.0
+[1.0.5]: https://github.com/cairnkeep/cairnkeep/compare/v1.0.4...v1.0.5

package/CONTRIBUTING.md

@@ -15,7 +15,9 @@ Contributions are welcome through GitHub issues and pull requests.
 
 ## Development setup
 
-The memory server requires Node.js 18 or newer. Node.js 20 is used in CI.
+The memory server requires Node.js 18 or newer. Node.js 22 or 24 is recommended
+for development; current CI uses Node.js 24 and retains a clean Node.js 18
+compatibility boot check.
 
 ```bash
 git clone https://github.com/cairnkeep/cairnkeep.git
@@ -47,3 +49,6 @@ endpoints. They are not part of the default offline test suite.
 
 By contributing, you agree that your contribution is licensed under the
 Apache License 2.0 found in [LICENSE](LICENSE).
+
+Release publishing is maintainer-only and documented in
+[docs/releasing.md](docs/releasing.md).

package/README.md

@@ -1,5 +1,9 @@
 # Cairnkeep
 
+[![CI](https://github.com/cairnkeep/cairnkeep/actions/workflows/ci.yml/badge.svg)](https://github.com/cairnkeep/cairnkeep/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@cairnkeep/cli)](https://www.npmjs.com/package/@cairnkeep/cli)
+[![license](https://img.shields.io/npm/l/@cairnkeep/cli)](LICENSE)
+
 > A durable, harness-agnostic **memory + context layer** for coding agents.
 
 A *cairn* is a stack of stones left as a trail marker for whoever follows; a
@@ -20,6 +24,23 @@ a thin routing seam (`route_check`), both of which delegate to
 [token-miser](https://github.com/cairnkeep/token-miser), a public
 cairnkeep-org sibling project.
 
+## Compatibility
+
+Node.js 22 or 24 is recommended. Node.js 18 and 20 remain compatible for the
+1.x line but are end-of-life upstream; the minimum will move in the next major
+release.
+
+| Client or platform | Support level |
+|---|---|
+| Claude Code on Linux/macOS | Memory server plus commands, agents, hooks, and launchers |
+| OpenCode on Linux/macOS | Memory server plus commands, plugins, hooks, and launchers |
+| Codex CLI | Memory MCP server; no Cairnkeep operating-layer assets |
+| Other MCP clients | Memory and optional domain-knowledge MCP tools |
+| Native Windows | Not supported by the Bash-based installer; use WSL (not yet CI-verified) |
+
+Linux, macOS, Bash 3.2 portability, and a clean Node 18 compatibility install
+are exercised in CI.
+
 ## Components
 
 - **`mcp-memory-server/`** — an MCP server exposing durable, scoped memory
@@ -85,6 +106,19 @@ cd /path/to/project && cairn doctor
 ./.ai/start-claude.sh
 ```
 
+After setup, the basic workflow is intentionally small:
+
+```text
+> /remember Use transactional migrations for schema changes
+Stored as patterns/transactional-migrations.
+
+> /recall transactional migrations
+patterns/transactional-migrations: Use transactional migrations for schema changes
+```
+
+The exact command rendering depends on the client. Any MCP client can call
+`memory_write` and `memory_search` directly.
+
 Prefer working from a clone? Build the server with `cd mcp-memory-server && npm
 install && npm run build`, then use `scripts/sync-claude-assets.sh` and
 `bin/cairn` in place of the installed `cairn`.
@@ -139,16 +173,25 @@ search):
 | `CAIRN_EXPLORE_REPO_ROOT` | Default repo root for `context_explore` when no per-call `repo_root` is given |
 | `CAIRN_EXTRA_SETTINGS` | Optional settings/config file the launcher layers onto the harness (wrapper seam) |
 | `CAIRN_ANYTHINGLLM_SYNC_SCRIPT` | Override path to the domain-knowledge sync script (when the integration lives outside the repo) |
+| `CAIRN_ANYTHINGLLM_PROJECTS_FILE` | Override path to the bundled sync script's project configuration |
+| `CAIRN_ANYTHINGLLM_STATE_FILE` | Override path to the bundled sync script's incremental state |
 
 Without an API key, search degrades gracefully to substring matching.
+There is no Cairnkeep telemetry. Optional extraction, embeddings, document RAG,
+remote memory, and delegated exploration can send content to endpoints you
+configure. Review [Privacy and data flow](docs/privacy-and-data-flow.md) before
+enabling them.
 
 ## More
 
 - **Optional document RAG** (`domain_knowledge_*` via AnythingLLM) — [docs/domain-knowledge.md](docs/domain-knowledge.md)
 - **Building a private overlay** (wrap cairnkeep for your org/provider) — [docs/building-an-overlay.md](docs/building-an-overlay.md)
+- **Managed overlay distributions** (wrapper CLI, policy lock, private registry, rollback) — [docs/overlay-distributions.md](docs/overlay-distributions.md)
 - **Full operating guide** — [docs/operating.md](docs/operating.md)
 - **Memory storage and deployment** — [docs/storage.md](docs/storage.md)
+- **Privacy and data flow** — [docs/privacy-and-data-flow.md](docs/privacy-and-data-flow.md)
 - **Git providers** — [docs/git-providers.md](docs/git-providers.md)
+- **Support** — [SUPPORT.md](SUPPORT.md)
 - **Contributing** — [CONTRIBUTING.md](CONTRIBUTING.md)
 - **Security policy** — [SECURITY.md](SECURITY.md)
 

package/docs/building-an-overlay.md

@@ -6,6 +6,11 @@ credentials, and no organization-specific launchers. Everything specific to
 launchers, policy — belongs in a small private **overlay** that wraps cairnkeep.
 This guide shows the pattern.
 
+For multi-machine or organization-wide use, package the overlay as a managed
+distribution that owns the enrolled machine's `cairn` command. See
+[Managed Cairnkeep distributions](overlay-distributions.md) for the command,
+manifest, profile-lock, private-registry, and rollback contract.
+
 ## Principles
 
 1. **Consume, don't fork.** Treat cairnkeep as an upstream dependency: install it
@@ -122,3 +127,7 @@ secret storage, not generated project files.
 - [ ] Operating layer scoped as intended (global vs `--live-root`)
 - [ ] Optional integrations wired only where wanted
 - [ ] A single documented command takes a fresh machine to a working setup
+- [ ] Managed machines resolve `cairn` to the overlay distribution, not raw core
+- [ ] `cairn config explain` reports memory and RAG destinations without secrets
+- [ ] A project profile lock prevents silent cross-overlay reconfiguration
+- [ ] Private packages reject public-registry publication and exclude runtime data

package/docs/domain-knowledge.md

@@ -28,7 +28,9 @@ work exactly the same without them.
 |---|---|
 | `ANYTHINGLLM_API_KEY` | **Required** for the domain-knowledge tools. Unset → the tools error at call time (everything else works). |
 | `ANYTHINGLLM_BASE_URL` | AnythingLLM base URL. Default `http://localhost:3001`. |
-| `CAIRN_ANYTHINGLLM_SYNC_SCRIPT` | Path to the document-sync script used by `domain_knowledge_sync`. The core does not bundle one — point this at your own (see below). Unset → `domain_knowledge_sync` uses the in-repo default path. |
+| `CAIRN_ANYTHINGLLM_SYNC_SCRIPT` | Optional path to a custom document-sync script. Unset -> `domain_knowledge_sync` uses the bundled deployment-neutral example. |
+| `CAIRN_ANYTHINGLLM_PROJECTS_FILE` | Optional config path for the bundled sync script. Default `${XDG_CONFIG_HOME:-~/.config}/cairnkeep/anythingllm-projects.json`. |
+| `CAIRN_ANYTHINGLLM_STATE_FILE` | Optional state path for the bundled sync script. Default `${XDG_STATE_HOME:-~/.local/state}/cairnkeep/anythingllm-sync.json`. |
 
 The workspaces the tools target come from the project's **memory config** — the
 first of `.agent/memory.json`, `.opencode/memory.json`, `.claude/memory.json`, or
@@ -73,10 +75,10 @@ returns a grounded answer.
 
 ## Setup (sync / embedding)
 
-`domain_knowledge_sync` shells out to a document-upload/embed script. Because the
-scripts that talk to your AnythingLLM (and any include/exclude rules) are
-deployment-specific, they live in **your** wrapper, not the core — point cairnkeep
-at yours:
+`domain_knowledge_sync` shells out to a document-upload/embed script. Cairnkeep
+ships a deployment-neutral example that reads its project mapping from a config
+file. For deployment-specific authentication, checkout rules, or document
+selection, keep a customized script in your overlay and point Cairnkeep at it:
 
 ```bash
 CAIRN_ANYTHINGLLM_SYNC_SCRIPT=/abs/path/to/your/sync_to_anythingllm.py
@@ -86,11 +88,13 @@ The script receives the workspace slug and is expected to upload + embed the
 project's documents into that AnythingLLM workspace. See
 [building-an-overlay.md](building-an-overlay.md) for the wrapper pattern.
 
-A working, deployment-agnostic starting point lives in
-[`examples/anythingllm/`](../examples/anythingllm/): an incremental
-(sha256-tracked) multi-project sync script plus a config schema. Copy it, adapt
-`anythingllm-projects.json`, and point `CAIRN_ANYTHINGLLM_SYNC_SCRIPT` at your
-copy.
+The bundled default lives in
+[`examples/anythingllm/`](../examples/anythingllm/): an incremental,
+SHA-256-tracked multi-project sync script plus a config schema. Put a customized
+copy of the example JSON at the default user config path, or set
+`CAIRN_ANYTHINGLLM_PROJECTS_FILE`. Existing custom scripts with configuration
+and state beside the script retain that legacy behavior. To customize the
+implementation itself, set `CAIRN_ANYTHINGLLM_SYNC_SCRIPT` to the adapted copy.
 
 ## Not using RAG?
 

package/docs/operating.md

@@ -156,6 +156,8 @@ vendor or host.
 | `ANYTHINGLLM_API_KEY` | Required to enable the optional `domain_knowledge_*` RAG tools (unset → those tools error at call time; nothing else affected). See [domain-knowledge.md](domain-knowledge.md) |
 | `ANYTHINGLLM_BASE_URL` | AnythingLLM base URL for `domain_knowledge_*` (default `http://localhost:3001`) |
 | `CAIRN_ANYTHINGLLM_SYNC_SCRIPT` | Override path to the `domain_knowledge_sync` document-sync script (unset → in-repo default) |
+| `CAIRN_ANYTHINGLLM_PROJECTS_FILE` | Override path to the bundled sync script's project configuration |
+| `CAIRN_ANYTHINGLLM_STATE_FILE` | Override path to the bundled sync script's incremental state |
 
 ### Domain knowledge (RAG via AnythingLLM, opt-in)
 

package/docs/overlay-distributions.md

@@ -0,0 +1,97 @@
+# Managed Cairnkeep distributions
+
+A private overlay becomes significantly easier to operate when it is treated as
+a **distribution** rather than a directory of configuration fragments. The
+distribution owns the `cairn` command on enrolled machines while consuming the
+public `@cairnkeep/cli` package as an exact dependency.
+
+This keeps Cairnkeep neutral and upgradeable. The distribution owns environment
+policy, data routing, launchers, private integrations, and delivery through an
+approved package registry. It should not patch or fork the core implementation.
+
+## Command contract
+
+An overlay package can expose its own `cairn` binary and delegate to its pinned
+core dependency:
+
+- `cairn bootstrap <project>` runs core bootstrap and then applies the overlay.
+- `cairn doctor` runs core diagnostics plus overlay policy checks.
+- `cairn config explain` reports effective storage and service destinations
+  without printing credentials.
+- `cairn overlay info` reports distribution and core versions separately.
+- `cairn core <command>` explicitly bypasses overlay behavior for diagnosis.
+- Other commands, especially `memory-server`, delegate to the pinned core with
+  the validated machine and project environment loaded.
+
+Do not replace core source files. A small wrapper preserves the upstream command
+surface while making managed bootstrap the default users reasonably expect.
+
+## Distribution manifest
+
+Store non-secret capabilities and data-routing policy in
+`cairnkeep.overlay.json`. The reference schema is
+[`schemas/cairnkeep-overlay.schema.json`](../schemas/cairnkeep-overlay.schema.json),
+with a complete example in
+[`examples/overlay-distribution`](../examples/overlay-distribution/cairnkeep.overlay.json).
+
+The distribution version and core version are independent. Pin the core exactly
+and test every distribution release against it.
+
+After a successful bootstrap, write an untracked project profile lock containing
+the distribution identity, versions, and non-secret policy. Refuse a different
+overlay identity before making changes. A stale lock should make `doctor` fail
+with an instruction to rerun managed bootstrap.
+
+## Configuration and secrets
+
+Use two explicit configuration layers:
+
+1. A mode-0600 machine profile in the user's configuration directory.
+2. An optional untracked, mode-0600 project override in `.ai/.env`.
+
+Validate both files before sourcing them: reject symlinks, permissive modes, and
+tracked project files. The manifest and project lock must never contain tokens,
+cookies, private keys, or credential-bearing URLs.
+
+`cairn config explain` should answer these questions directly:
+
+- Is memory local or remote?
+- Which transport is used?
+- Which directory or endpoint receives memory?
+- Is document RAG disabled, local, or remote?
+- Which configuration files selected those values?
+
+## Private package delivery
+
+A distribution can be an ordinary scoped npm package with:
+
+- `@cairnkeep/cli` as an exact dependency;
+- a `bin.cairn` entry for the wrapper;
+- `publishConfig.access` set to `restricted`;
+- an explicit guard that rejects the public npm registry;
+- registry credentials supplied by a user credential helper or protected CI
+  variables, never by repository files.
+
+Support installation from a private registry, a reviewed tarball, and a local
+checkout. Avoid `postinstall` enrollment: installing a package must not silently
+replace machine policy. Provide an explicit enrollment command with a retained
+rollback target.
+
+## Release and fleet safety
+
+Every release should verify:
+
+- fresh managed bootstrap and idempotent reruns;
+- core delegation and the explicit core escape hatch;
+- profile mismatch rejection before mutation;
+- storage and RAG policy enforcement;
+- secret and runtime-artifact exclusion from the package;
+- package installation from the produced tarball;
+- checksums, an SBOM, and an immutable version;
+- pre-upgrade and post-upgrade `doctor` results;
+- rollback to the previous command or package version.
+
+For a fleet migration, update the machine operating layer once, reapply managed
+bootstrap to projects without altering tracked Git status, and validate every
+profile lock. Storage migrations require their own backup, integrity, canary,
+and rollback procedure; changing an overlay version alone must not move data.

package/docs/privacy-and-data-flow.md

@@ -0,0 +1,49 @@
+# Privacy and data flow
+
+Cairnkeep has no telemetry, analytics collector, hosted control plane, or
+automatic remote-service discovery. A default local stdio installation stores
+memory in SQLite on the machine running the MCP server and makes no model or RAG
+request unless the corresponding endpoint and credential are configured.
+
+## Data flows
+
+| Feature | Data that can leave the server machine | Destination |
+|---|---|---|
+| Local substring search | None | Local SQLite only |
+| Embedding-ranked search | Stored memory values that are not cached, plus the search query | `CAIRN_MEMORY_EMBEDDING_URL` or `CAIRN_LLM_API_URL` |
+| `memory_extract` | The transcript supplied to the tool | `CAIRN_LLM_API_URL` |
+| `domain_knowledge_query` | Workspace slug and query | `ANYTHINGLLM_BASE_URL` |
+| `domain_knowledge_sync` | Files selected by the sync configuration | `ANYTHINGLLM_BASE_URL` |
+| `route_check` | A health request, with no memory or prompt content | `CAIRN_ROUTE_ENDPOINT` |
+| `context_explore` | Repository path and query are passed to the configured local executable | `CAIRN_EXPLORE_BINARY`; any further data flow is controlled by that tool |
+| Remote HTTP memory | MCP requests and responses, including memory content | The explicitly registered Cairnkeep HTTP server |
+
+Model endpoints may be local or remote. Cairnkeep cannot determine a provider's
+retention, training, or logging policy; verify it before sending confidential
+material. Disabling `CAIRN_LLM_API_KEY`, `ANYTHINGLLM_API_KEY`, remote HTTP
+registration, and delegated tools keeps the core memory workflow local.
+
+## Data at rest
+
+Memories are stored in SQLite databases. They are not encrypted by Cairnkeep at
+the application layer. Use operating-system disk encryption, restrictive file
+permissions, encrypted backups, and host access controls appropriate to the
+sensitivity of the material. SQLite `-wal` and `-shm` sidecars and exported
+archives can contain sensitive content too.
+
+Project-scoped and named/global database locations are documented in
+[Memory storage and deployment](storage.md). A remote client stores memory on
+the remote server host; changing a storage environment variable on the client
+does not relocate that server's databases.
+
+## Credentials and transport
+
+Keep API keys and bearer tokens out of repositories and command output. Load
+them from a secret manager or protected environment file. For remote HTTP mode,
+use TLS or an encrypted private network and keep the raw listener on loopback.
+One HTTP bearer token grants access to the entire server; Cairnkeep does not
+provide tenant isolation or per-scope authorization.
+
+Before sharing diagnostics, remove credentials, private endpoints, database
+files, memory values, local paths, and project names. Report vulnerabilities
+through the private channel in [SECURITY.md](../SECURITY.md).

package/docs/releasing.md

@@ -0,0 +1,33 @@
+# Releasing
+
+Publishing is driven by a GitHub Release. Maintainers do not publish the package
+from a workstation.
+
+## Release contract
+
+1. Update the root `package.json` version and `CHANGELOG.md` on a pull request.
+2. Run `npm ci`, `npm run check:public`, and
+   `npm --prefix mcp-memory-server test`.
+3. Merge only after every required CI check passes.
+4. Publish a GitHub Release whose tag is exactly `v<package.json version>`.
+5. The `Publish release` workflow checks out that immutable tag, repeats the
+   tests, and publishes `@cairnkeep/cli` with npm provenance.
+6. The workflow attaches the npm tarball, a CycloneDX SBOM, and SHA-256 checksums
+   to the GitHub Release.
+
+Stable versions must use a stable GitHub Release and publish to npm's `latest`
+tag. SemVer prerelease versions must use a GitHub prerelease and publish to
+`next`. A mismatch fails before publication.
+
+The workflow is safe to rerun: it skips `npm publish` when that exact version is
+already present, then regenerates and replaces the release artifacts.
+
+## Repository configuration
+
+The repository must provide an `NPM_TOKEN` Actions secret authorized to publish
+`@cairnkeep/cli`. Keep that credential out of local files and rotate it according
+to the npm account's security policy. The workflow grants only `contents: write`
+and `id-token: write`; the latter is required for npm provenance.
+
+Treat a published version as immutable. If a release is wrong, fix it in a new
+version rather than moving its tag or replacing the npm package.

package/docs/storage.md

@@ -129,8 +129,18 @@ claude mcp remove cairn-memory -s user 2>/dev/null || true
 claude mcp add --transport http -s user \
   cairn-memory "$CAIRN_MEMORY_REMOTE_URL" \
   --header "Authorization: Bearer $CAIRN_MEMORY_HTTP_TOKEN"
+
+codex mcp remove cairn-memory 2>/dev/null || true
+codex mcp add cairn-memory \
+  --url "$CAIRN_MEMORY_REMOTE_URL" \
+  --bearer-token-env-var CAIRN_MEMORY_HTTP_TOKEN
 ```
 
+Codex reads the bearer token from the named environment variable when it
+starts. Do not run `codex mcp login cairn-memory`: that command starts an OAuth
+flow, while Cairnkeep intentionally uses a static bearer token and advertises
+no OAuth authorization endpoint.
+
 OpenCode is configured separately in its per-user `opencode.json`. It supports
 environment references in remote MCP headers, so the token does not need to be
 written literally into the JSON:
@@ -161,3 +171,17 @@ expands `${VAR}` references in project `.mcp.json` URL and header values;
 OpenCode uses `{env:VAR}` references. A private overlay should generate and
 merge these files so secrets remain in the process environment rather than the
 repository.
+
+For Codex, put the routing configuration in the trusted project's private
+`.codex/config.toml` and exclude it from version control:
+
+```toml
+[mcp_servers.cairn-memory]
+url = "https://memory.example.com/mcp"
+bearer_token_env_var = "CAIRN_MEMORY_HTTP_TOKEN"
+
+[mcp_servers.cairn-memory.http_headers]
+"X-Cairn-Project" = "example-project"
+"X-Cairn-Scopes" = "identity,personal,project"
+"X-Cairn-AnythingLLM-Workspaces" = "engineering-patterns"
+```

package/examples/anythingllm/README.md

@@ -0,0 +1,66 @@
+# AnythingLLM sync — reference example
+
+The bundled reference implementation of the document-sync script that
+Cairnkeep's `domain_knowledge_sync` tool shells out to. It is a usable,
+deployment-neutral starting point; copy and adapt it when endpoint,
+authentication, or include/exclude rules are deployment-specific.
+
+See [`../../docs/domain-knowledge.md`](../../docs/domain-knowledge.md) for the
+full RAG picture.
+
+## What it does
+
+Incrementally syncs each configured project's docs into its own AnythingLLM
+workspace: creates the workspace, uploads changed files (tracked by sha256),
+embeds them, and removes docs that disappeared. Supports `--dry-run`, `--full`,
+`--replace`, `--rebuild-state`, `--list`, and `--project <slug>`.
+
+## Setup
+
+1. Requires Python 3 and `requests` (`pip install requests`).
+2. Copy the config to the default user config location and fill in your
+   projects:
+   ```bash
+   mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/cairnkeep"
+   cp anythingllm-projects.example.json \
+     "${XDG_CONFIG_HOME:-$HOME/.config}/cairnkeep/anythingllm-projects.json"
+   # edit: set each project's absolute path, slug, and include/exclude globs
+   ```
+3. Point at your AnythingLLM instance:
+   ```bash
+   export ANYTHINGLLM_BASE_URL=http://localhost:3001   # default
+   export ANYTHINGLLM_API_KEY=<your AnythingLLM API key>
+   ```
+4. First upload, then keep it in sync:
+   ```bash
+   python3 sync_to_anythingllm.py --full --project my-project
+   python3 sync_to_anythingllm.py                       # incremental, all projects
+   ```
+
+## Wiring into cairnkeep
+
+The installed server uses this script by default. To use an adapted copy, set:
+
+```bash
+CAIRN_ANYTHINGLLM_SYNC_SCRIPT=/abs/path/to/sync_to_anythingllm.py
+```
+
+Override the user-owned configuration or state locations when needed:
+
+```bash
+CAIRN_ANYTHINGLLM_PROJECTS_FILE=/abs/path/to/anythingllm-projects.json
+CAIRN_ANYTHINGLLM_STATE_FILE=/abs/path/to/anythingllm-sync.json
+```
+
+For backward compatibility, an existing `anythingllm-projects.json` beside a
+customized script and its `.anythingllm-sync.json` state are still used when the
+override variables are unset.
+
+## Files
+
+| File | Committed? | Notes |
+|---|---|---|
+| `sync_to_anythingllm.py` | yes | the script |
+| `anythingllm-projects.example.json` | yes | schema template |
+| `anythingllm-projects.json` | **no** | User-owned config; defaults under the XDG config directory |
+| `anythingllm-sync.json` | **no** | Machine-local SHA-256 state; defaults under the XDG state directory |

package/examples/anythingllm/anythingllm-projects.example.json

@@ -0,0 +1,30 @@
+{
+  "projects": [
+    {
+      "slug": "my-project",
+      "display_name": "My Project Documentation",
+      "path": "/abs/path/to/my-project",
+      "patterns": [
+        "README.md",
+        "docs/**/*.md"
+      ],
+      "exclude_patterns": [
+        "CHANGELOG.md",
+        "LICENSE.md"
+      ]
+    },
+    {
+      "slug": "another-project",
+      "display_name": "Another Project Docs",
+      "path": "/abs/path/to/another-project",
+      "patterns": [
+        "AGENTS.md",
+        "docs/**/*.md",
+        ".planning/wiki/**/*.md"
+      ],
+      "exclude_patterns": [
+        ".planning/wiki/tmp/**"
+      ]
+    }
+  ]
+}