@time-machine-lab/tmlbrain 0.1.0 → 0.1.2

package/docs/architecture.md

@@ -50,6 +50,19 @@ editing interface, and clients do not push to it.
 The Docker image intentionally contains only the TMLBrain tool and knowledge
 templates. It must not contain real team knowledge.
 
+## Knowledge Placement
+
+Archive, store, save, and record are equivalent user intents for adding content
+to TMLBrain. New knowledge is classified into the approved taxonomy by default:
+
+- `project`, `meeting`, and `decision` content goes under `knowledge/10-projects/`.
+- `area` content goes under `knowledge/20-areas/`.
+- `resource` content goes under `knowledge/30-resources/`.
+- `reference` content goes under `knowledge/40-references/`.
+
+`knowledge/00-inbox/` is reserved for genuinely unclassified or explicitly
+temporary capture, not as the default destination for normal saves.
+
 ## Release Workflow
 
 The npm client package, Docker server image, and server deployment are handled
@@ -72,7 +85,13 @@ After pushing the image, the workflow logs in to the configured server with
 restarts the `tmlbrain-server` container. Runtime knowledge repository
 credentials are passed to the server as mounted secrets or environment
 configuration; they are never baked into the image. Knowledge repository URLs
-must be HTTPS URLs and use `TMLBRAIN_KNOWLEDGE_TOKEN`.
+must be HTTPS URLs and use `TMLBRAIN_KNOWLEDGE_TOKEN`. Deployment validates the
+knowledge repository URL and token before replacing the running server.
+
+If the server needs a proxy for GitHub, deployment can use
+`TMLBRAIN_SERVER_GIT_PROXY_URL` or an existing `tmlbrain-proxy` container. The
+proxy is configured as a Git-only proxy for `https://github.com`, so normal
+server API traffic is unchanged.
 
 ## Search And Graph Layer
 

package/docs/backup.md

@@ -6,9 +6,9 @@ The dedicated knowledge repository is used for disaster recovery, reviewable
 history, first-boot restore, and off-server backup. It is not the primary
 editing surface.
 
-The server needs a dedicated knowledge repository credential only if it is
-expected to push backup state to a private GitHub repository. Clients never
-need repository write credentials.
+The server needs a dedicated knowledge repository credential if it is expected
+to push backup state to GitHub. Clients never need repository write
+credentials.
 
 If TMLBrain must upload modified server knowledge back to GitHub, the running
 server needs write authorization for the dedicated knowledge repository. GitHub
@@ -27,7 +27,7 @@ Recommended credential option:
 Do not bake knowledge repository credentials into the Docker image. Do not
 commit them to the project configuration. GitHub Actions secrets can be used to
 deploy the credential to the server or create a Docker secret, but the running
-server still needs access to a credential when it performs `tmlbrain backup`.
+server still needs access to a credential when it performs backup.
 
 The auto-release workflow supports this deployment pattern with:
 
@@ -40,6 +40,18 @@ TMLBRAIN_KNOWLEDGE_REF
 `TMLBRAIN_KNOWLEDGE_REPO` must be an HTTPS repository URL. The workflow writes
 `TMLBRAIN_KNOWLEDGE_TOKEN` to a mounted secret file and uses `GIT_ASKPASS`
 inside the container, so Git can clone on first boot and push backups later.
+During deployment, the workflow validates the repository URL and token before
+restarting the server container.
+
+If the server cannot reach GitHub directly, set:
+
+```text
+TMLBRAIN_SERVER_GIT_PROXY_URL
+```
+
+This proxy is scoped to Git operations for `https://github.com` only. If the
+secret is not set but a `tmlbrain-proxy` container exists on the server, the
+deployment uses that container automatically.
 
 ## Dry Run
 
@@ -51,6 +63,46 @@ tmlbrain backup --dry-run --remote backup
 
 The command reports the source commit, target remote, and whether the target remote exists. Backup attempts are logged under `.tmlbrain/logs/backup.log`.
 
+## Write-Time Backup
+
+When a server API write creates a new commit, the server first pushes that
+commit to its local `origin` bare repository, then attempts to push `HEAD` to
+the configured `backup` remote. The backup result is returned in the API
+response and appended to `.tmlbrain/logs/backup.log`.
+
+Backup failure does not roll back the accepted knowledge write. Maintainers can
+inspect the backup log and rerun:
+
+```text
+tmlbrain backup --remote backup
+```
+
+## Scheduled Backup
+
+Write-time backup is the primary path. Scheduled backup is a server-side
+fallback for missed pushes or manual server maintenance.
+
+Docker deployments can enable the fallback loop with:
+
+```text
+TMLBRAIN_BACKUP_INTERVAL_SECONDS=900
+TMLBRAIN_BACKUP_REMOTE=backup
+```
+
+When the interval is greater than zero, the container starts
+`scripts/backup/scheduled-backup.sh` in the background and runs
+`tmlbrain backup --remote <remote>` from `/data/worktree` at that interval.
+
+Non-Docker deployments can use the templates:
+
+```text
+scripts/backup/tmlbrain-backup.service
+scripts/backup/tmlbrain-backup.timer
+```
+
+Copy them to `/etc/systemd/system/`, adjust paths if needed, then enable the
+timer.
+
 For Docker deployments, keep Git inside the server image or sidecar because the
 server write path still commits and pushes. The client runtime can remain
 HTTP-only and does not need Git.
@@ -60,7 +112,7 @@ HTTP-only and does not need Git.
 For Docker deployments, first-boot restore can be handled by:
 
 ```text
-TMLBRAIN_KNOWLEDGE_REPO=https://github.com/Time-Machine-Lab/TMLBrainKnowledge.git
+TMLBRAIN_KNOWLEDGE_REPO=https://github.com/Time-Machine-Lab/Knowledge.git
 ```
 
 If `/data/worktree` is missing, the container clones that repository. If the

package/docs/indexing.md

@@ -6,8 +6,8 @@ TMLBrain retrieval is local-first:
 
 1. Exact search with ripgrep or the CLI fallback.
 2. Deterministic Markdown index generated by `tmlbrain index`.
-3. Optional CocoIndex incremental pipeline.
-4. Optional LightRAG graph and semantic retrieval.
+3. CocoIndex-compatible incremental pipeline through `tmlbrain graph index`.
+4. LightRAG-compatible graph and semantic retrieval through `tmlbrain graph query`.
 
 ## Deterministic Index
 
@@ -22,11 +22,30 @@ These files are local generated artifacts and must not be pushed to the server.
 
 ## Graph Runtime
 
-CocoIndex and LightRAG are preferred for the fuller graph retrieval pipeline, but exact search and the deterministic index remain available when the graph runtime is disabled.
+CocoIndex and LightRAG are preferred for the fuller graph retrieval pipeline,
+but exact search and the deterministic index remain available when the graph
+runtime is disabled or optional packages are unavailable.
 
 Optional adapter entrypoints live in:
 
 - `scripts/index/cocoindex_pipeline.py`
 - `scripts/index/lightrag_retrieval.py`
 
-They intentionally return degraded status when the Python graph packages are not installed. A later implementation pass should wire them to a real CocoIndex flow and provider-configured LightRAG storage/retrieval setup.
+Use:
+
+```text
+tmlbrain graph index --json
+tmlbrain graph query "question" --json
+```
+
+`tmlbrain graph index` scans `knowledge/**/*.md`, parses front matter,
+headings, chunks, hashes, Markdown links, wiki links, heading anchors, and
+backlinks, then writes local artifacts under `.tmlbrain/index/cocoindex/`.
+It reuses the previous manifest to skip unchanged document entries by content
+hash.
+
+`tmlbrain graph query` reads the CocoIndex-compatible chunks and graph context,
+then returns ranked local chunks with source paths, line ranges, document
+metadata, and related graph edges. When LightRAG is installed/configured, the
+adapter reports the preferred engine as available; otherwise it uses the
+deterministic local compatible retriever and reports degraded status.

package/docs/install.md

@@ -2,10 +2,11 @@
 
 ## Client
 
-Recommended interactive install:
+Recommended npm install:
 
 ```text
-npx @time-machine-lab/tmlbrain client install
+npm install -g @time-machine-lab/tmlbrain@latest
+tmlbrain client install
 ```
 
 The installer asks for:
@@ -19,21 +20,31 @@ search, index, and save Markdown under the local `knowledge/` folder. They can
 connect to a team server later:
 
 ```text
-tmlbrain config set-server http://server-host:7389 --token <token>
+tmlbrain config set-server http://server-host:8477 --token <token>
 tmlbrain sync --pull
 ```
 
-Non-interactive client install:
+Non-interactive npm install:
 
 ```text
-npx @time-machine-lab/tmlbrain client install --server http://server-host:7389 --token <token> --yes
+npm install -g @time-machine-lab/tmlbrain@latest
+tmlbrain client install --server http://server-host:8477 --token <token> --yes
 ```
 
-Global install is also supported after the npm package is published:
+Update an existing npm-installed client:
 
 ```text
-npm install -g @time-machine-lab/tmlbrain
-tmlbrain client install
+tmlbrain update
+```
+
+`tmlbrain update` runs `npm install -g @time-machine-lab/tmlbrain@latest`,
+refreshes the local Skill/runtime, and preserves the existing server URL and
+token. Use `tmlbrain update 0.1.1` to update to a specific version.
+
+Optional one-time npx install without keeping a global command:
+
+```text
+npx -y @time-machine-lab/tmlbrain@latest client install
 ```
 
 ## Server
@@ -45,9 +56,9 @@ skeleton.
 
 ```text
 docker run -d --name tmlbrain-server \
-  -p 7389:7389 \
+  -p 8477:8477 \
   -e TMLBRAIN_SERVER_TOKEN=<required-token> \
-  -e TMLBRAIN_KNOWLEDGE_REPO=https://github.com/Time-Machine-Lab/TMLBrainKnowledge.git \
+  -e TMLBRAIN_KNOWLEDGE_REPO=https://github.com/Time-Machine-Lab/Knowledge.git \
   -e TMLBRAIN_KNOWLEDGE_REF=main \
   -v tmlbrain-data:/data \
   <DOCKER_REPO>:latest
@@ -72,7 +83,7 @@ The Docker image does not contain real team knowledge. Real knowledge should be
 stored in a separate private repository, for example:
 
 ```text
-https://github.com/Time-Machine-Lab/TMLBrainKnowledge.git
+https://github.com/Time-Machine-Lab/Knowledge.git
 ```
 
 That repository must contain the TMLBrain `knowledge/` directory at its root.
@@ -89,7 +100,11 @@ repository configured in GitHub Actions secret `DOCKER_REPO`. The npm client
 package is published by the same workflow with the `NPM_TOKEN` repository
 secret. The workflow then logs in to the target server with
 `SERVER_HOST`, `SERVER_USER`, and `SERVER_PWD`, pulls the new image, and
-restarts the `tmlbrain-server` container.
+restarts the `tmlbrain-server` container. Server-side Docker login is skipped
+by default because the runtime image is expected to be public; only the GitHub
+Actions runner needs Docker credentials to push the image. For a private image,
+set `TMLBRAIN_SERVER_DOCKER_LOGIN=true` and provide
+`TMLBRAIN_SERVER_DOCKER_USERNAME` plus `TMLBRAIN_SERVER_DOCKER_PASSWORD`.
 
 ```text
 <DOCKER_REPO>:latest
@@ -119,7 +134,7 @@ TMLBRAIN_KNOWLEDGE_REF
 ```
 
 `TMLBRAIN_KNOWLEDGE_REPO` must be an HTTPS URL, for example
-`https://github.com/Time-Machine-Lab/TMLBrainKnowledge.git`.
+`https://github.com/Time-Machine-Lab/Knowledge.git`.
 `TMLBRAIN_KNOWLEDGE_TOKEN` must be a GitHub token with write access to that
 dedicated knowledge repository. Fine-grained tokens are preferred; classic
 tokens also work when they have the right repository scope: use `repo` for
@@ -127,6 +142,20 @@ private repositories, or `public_repo` only for public repositories. This
 credential belongs to the server runtime, not to clients and not to the Docker
 image.
 
+Optional GitHub connectivity secret:
+
+```text
+TMLBRAIN_SERVER_GIT_PROXY_URL
+```
+
+Use this only when the deployment server cannot reach GitHub directly. The
+workflow applies the proxy to Git operations for `https://github.com` only. If
+the secret is absent but a `tmlbrain-proxy` container is running on the server,
+deployment connects the TMLBrain server container to that proxy automatically.
+Before replacing the running server, the workflow validates
+`TMLBRAIN_KNOWLEDGE_REPO` plus `TMLBRAIN_KNOWLEDGE_TOKEN` with Git so a broken
+token does not create a bad deployment.
+
 ## Release Command Format
 
 Releases are driven by the HEAD commit message on `main`. The workflow skips
@@ -135,7 +164,7 @@ commits that do not contain `<Auto>`.
 Example:
 
 ```text
-[tml-brain]<Auto> release server and client -v:0.1.0 -rp:7389 -de:<-e KEY=value>
+[tml-brain]<Auto> release server and client -v:0.1.0 -rp:8477 -de:<-e KEY=value>
 ```
 
 Fields:
@@ -143,7 +172,7 @@ Fields:
 - `<Auto>` is required to trigger publishing.
 - `-v:<semver>` is required and is used for both npm and Docker versions. Use a
   Docker-compatible value such as `0.1.0` or `0.1.0-beta.1`.
-- `-rp:<port>` is optional and defaults to `7389`; it becomes the Docker image
+- `-rp:<port>` is optional and defaults to `8477`; it becomes the Docker image
   default `TMLBRAIN_PORT`.
 - `-de:<...>` is optional single-line Docker runtime metadata, such as
   additional `docker run -e` arguments. It stays in the commit message and is

package/docs/runtime.md

@@ -5,7 +5,8 @@
 TMLBrain should feel like one product to the user:
 
 ```text
-npx @time-machine-lab/tmlbrain client install
+npm install -g @time-machine-lab/tmlbrain@latest
+tmlbrain client install
 @TMLBrain search or update knowledge
 ```
 
@@ -21,7 +22,7 @@ The core runtime must work without Python:
 - Local workspace state under `.tmlbrain/`.
 - Exact search.
 - Markdown validation.
-- Document creation.
+- Document creation with taxonomy-based placement.
 - Server API write requests.
 - Read-only snapshot sync.
 
@@ -34,16 +35,22 @@ CocoIndex and LightRAG are optional graph retrieval features. They are enabled b
 
 ```text
 tmlbrain graph setup
+tmlbrain graph index
+tmlbrain graph query "question"
 ```
 
-If Python, CocoIndex, or LightRAG cannot be activated, core TMLBrain remains usable in degraded search mode.
+If Python cannot be activated, core TMLBrain remains usable in degraded search
+mode. If Python is available but CocoIndex or LightRAG packages are missing,
+the graph commands use compatible local adapters and report degraded status
+instead of blocking exact search or deterministic indexing.
 
 ## Installer Entry Points
 
 Recommended npm client entry:
 
 ```text
-npx @time-machine-lab/tmlbrain client install
+npm install -g @time-machine-lab/tmlbrain@latest
+tmlbrain client install
 ```
 
 The client installer asks for a server URL. Leaving it empty starts local-only
@@ -66,7 +73,8 @@ Both scripts call the same CLI bootstrap flow and keep the user away from raw Gi
 Non-interactive client install:
 
 ```text
-npx @time-machine-lab/tmlbrain client install --server http://server-host:7389 --token secret --yes
+npm install -g @time-machine-lab/tmlbrain@latest
+tmlbrain client install --server http://server-host:8477 --token secret --yes
 ```
 
 ## Server Runtime
@@ -74,7 +82,7 @@ npx @time-machine-lab/tmlbrain client install --server http://server-host:7389 -
 Run with Docker:
 
 ```text
-docker run -d --name tmlbrain-server -p 7389:7389 -e TMLBRAIN_SERVER_TOKEN=secret -e TMLBRAIN_KNOWLEDGE_REPO=https://github.com/Time-Machine-Lab/TMLBrainKnowledge.git -v tmlbrain-data:/data <DOCKER_REPO>:latest
+docker run -d --name tmlbrain-server -p 8477:8477 -e TMLBRAIN_SERVER_TOKEN=secret -e TMLBRAIN_KNOWLEDGE_REPO=https://github.com/Time-Machine-Lab/Knowledge.git -v tmlbrain-data:/data <DOCKER_REPO>:latest
 ```
 
 The image contains tooling and templates only. Real knowledge is restored from
@@ -86,10 +94,19 @@ port with `-e TMLBRAIN_PORT=<port>` and the corresponding Docker `-p` mapping.
 Manual development mode from the server worktree:
 
 ```text
-node bin/tmlbrain.js serve --host 0.0.0.0 --port 7389
+node bin/tmlbrain.js serve --host 0.0.0.0 --port 8477
 ```
 
 Only the server runtime should mutate Markdown, commit repository changes, or
 push to the dedicated knowledge repository. Clients should use `tmlbrain sync
---pull` for snapshots, `tmlbrain find` for local search, and `tmlbrain save` or
-`tmlbrain remote update` for write requests.
+--pull` for snapshots, `tmlbrain find` for local search, and `tmlbrain save`,
+`tmlbrain remote update`, or explicit `tmlbrain remote delete` for write
+requests. Normal `tmlbrain save` requests classify content into the knowledge
+taxonomy; `00-inbox` is reserved for genuinely unclear or explicitly temporary
+capture. Deletion is reserved for explicit user intent; otherwise prefer
+marking content stale.
+
+Server writes attempt GitHub backup immediately after an accepted commit. A
+scheduled fallback can be enabled in Docker with
+`TMLBRAIN_BACKUP_INTERVAL_SECONDS`; systemd timer templates are available under
+`scripts/backup/` for non-Docker deployments.

package/docs/server-api.md

@@ -5,7 +5,15 @@ TMLBrain uses a server-owned write boundary.
 Clients keep a read-only local snapshot for search and indexing. Clients request
 knowledge mutations through the TMLBrain server API. The server mutates
 Markdown, validates the knowledge base, commits the repository change, and then
-pushes from the server worktree to the server bare repository.
+pushes from the server worktree to the server bare repository. After a
+successful write commit, the server also attempts to push the same commit to
+the configured `backup` remote so the dedicated GitHub knowledge repository
+stays current.
+
+For new knowledge, archive/store/save/record requests are treated as the same
+save operation. The client and server classify the document into the approved
+taxonomy by default; `00-inbox` is reserved for genuinely unclear or explicitly
+temporary capture.
 
 ## Run The Server
 
@@ -13,9 +21,9 @@ Recommended Docker deployment:
 
 ```text
 docker run -d --name tmlbrain-server \
-  -p 7389:7389 \
+  -p 8477:8477 \
   -e TMLBRAIN_SERVER_TOKEN=secret \
-  -e TMLBRAIN_KNOWLEDGE_REPO=https://github.com/Time-Machine-Lab/TMLBrainKnowledge.git \
+  -e TMLBRAIN_KNOWLEDGE_REPO=https://github.com/Time-Machine-Lab/Knowledge.git \
   -v tmlbrain-data:/data \
   <DOCKER_REPO>:latest
 ```
@@ -24,22 +32,29 @@ docker run -d --name tmlbrain-server \
 data volume already contains `/data/worktree`, the container reuses that
 worktree instead of cloning again.
 
+For private GitHub knowledge repositories, deploy the server with
+`TMLBRAIN_KNOWLEDGE_TOKEN` as a runtime secret. If the server cannot reach
+GitHub directly, deployment may set `TMLBRAIN_SERVER_GIT_PROXY_URL` or reuse an
+existing `tmlbrain-proxy` container; that proxy is applied only to GitHub Git
+traffic.
+
 Run from the server worktree:
 
 ```text
-node bin/tmlbrain.js serve --host 0.0.0.0 --port 7389
+node bin/tmlbrain.js serve --host 0.0.0.0 --port 8477
 ```
 
 Optional token protection:
 
 ```text
-TMLBRAIN_SERVER_TOKEN=secret node bin/tmlbrain.js serve --host 0.0.0.0 --port 7389
+TMLBRAIN_SERVER_TOKEN=secret node bin/tmlbrain.js serve --host 0.0.0.0 --port 8477
 ```
 
 Clients then install with:
 
 ```text
-npx @time-machine-lab/tmlbrain client install --server http://server-host:7389 --token secret --yes
+npm install -g @time-machine-lab/tmlbrain@latest
+tmlbrain client install --server http://server-host:8477 --token secret --yes
 ```
 
 The client stores this in `.tmlbrain/state.json`. The token is not shown by
@@ -54,19 +69,19 @@ node bin/tmlbrain.js config show
 Switch a client to a different server:
 
 ```text
-node bin/tmlbrain.js config set-server http://new-server-host:7389 --token secret
+node bin/tmlbrain.js config set-server http://new-server-host:8477 --token secret
 node bin/tmlbrain.js sync --pull
 ```
 
 `--server` and `--token` can also be passed to one command for temporary
 overrides.
 
-If the cloud security group does not expose port `7389`, keep the API private
+If the cloud security group does not expose port `8477`, keep the API private
 and use a tunnel from the client machine:
 
 ```text
-ssh -N -L 7390:127.0.0.1:7389 tmlbrain-1007
-npx @time-machine-lab/tmlbrain client install --server http://127.0.0.1:7390 --token secret --yes
+ssh -N -L 8478:127.0.0.1:8477 tmlbrain-1007
+tmlbrain client install --server http://127.0.0.1:8478 --token secret --yes
 ```
 
 ## Client Commands
@@ -101,19 +116,53 @@ Ask the server to update a precise text region:
 node bin/tmlbrain.js remote update --file knowledge/00-inbox/note.md --replace "old text" --with "new text"
 ```
 
+Ask the server to delete a knowledge document only after the user explicitly
+requests deletion:
+
+```text
+node bin/tmlbrain.js remote delete --file knowledge/30-resources/old-note.md
+```
+
+Normal client updates automatically include the last synced file hash as
+`expectedSha256` when the local snapshot has one. If the server document has
+changed, the server returns a structured `409` conflict containing the current
+hash, relevant current text, rejected intent, reason, and suggested next
+actions. Delete requests use the same stale-file protection when the local
+snapshot has a file hash. The CLI turns that response into a local TMLBrain
+conflict package and refreshes the snapshot when possible.
+
 ## API Endpoints
 
 - `GET /health`: server health and current head.
 - `GET /capabilities`: machine-readable command and boundary description.
 - `GET /snapshot`: read-only Markdown snapshot for clients.
-- `POST /knowledge/add`: server-side add, validate, commit, and push.
-- `POST /knowledge/update`: server-side replace or content-file update, validate, commit, and push.
+- `POST /knowledge/add`: server-side classified add, validate, commit, push to local server repository, and attempt GitHub backup.
+- `POST /knowledge/update`: server-side replace or content-file update, validate, commit, push to local server repository, and attempt GitHub backup.
+- `POST /knowledge/delete`: server-side Markdown document delete, validate, commit, push to local server repository, and attempt GitHub backup.
+
+Structured update conflicts return:
+
+```json
+{
+  "ok": false,
+  "error": "Expected sha256 ...",
+  "conflict": {
+    "path": "knowledge/...",
+    "reason": "expected-sha256-mismatch",
+    "currentSha256": "...",
+    "expectedSha256": "...",
+    "currentRelevantText": "...",
+    "rejectedIntent": {},
+    "suggestedNextActions": []
+  }
+}
+```
 
 ## Boundary
 
 Clients MUST NOT push to the server Git repository or dedicated knowledge
 repository. Backing up to that repository remains a server-side operation
-through `tmlbrain backup`.
+through write-time backup and `tmlbrain backup`.
 
 HTTP-only clients do not need Git installed. The server runtime still needs Git
 because it validates, commits, pushes to the server bare repository, and runs

package/docs/sync.md

@@ -14,8 +14,14 @@ Users ask TMLBrain to write knowledge through the server:
 tmlbrain save --title "Title" --content "Content"
 tmlbrain save ./note.md
 tmlbrain remote update --file knowledge/00-inbox/note.md --replace "old" --with "new"
+tmlbrain remote delete --file knowledge/30-resources/old-note.md
 ```
 
+Archive, store, save, and record are equivalent user intents for adding content
+to the knowledge base. Save requests classify content into the approved
+taxonomy by default. `00-inbox` is only used when the correct long-term folder
+is genuinely unclear or explicitly requested.
+
 They should not need to run `git pull`, `git push`, `git merge`, or `git rebase`.
 Clients also should not perform hidden Git writes to the server. In the
 HTTP-only workflow, clients do not need Git installed.
@@ -35,9 +41,14 @@ client write request
   -> server validation
   -> server Git commit
   -> server bare repository
-  -> dedicated knowledge repository backup
+  -> dedicated knowledge repository backup attempt
 ```
 
+`tmlbrain remote delete` is a server-owned write request too. Clients only send
+the explicit delete intent; the server performs the file removal, validates the
+remaining knowledge base, commits the change, pushes the server repository, and
+attempts the dedicated GitHub backup.
+
 ## Conflict Handling
 
 When the server cannot apply a requested update safely, it rejects the request
@@ -45,10 +56,19 @@ instead of silently overwriting remote knowledge. For precise text replacement,
 the server requires the replacement text to match exactly once unless a broader
 operation is explicitly requested.
 
+For normal `tmlbrain remote update` requests, the client reads the last synced
+file hash from `.tmlbrain/state.json` and sends it as `expectedSha256`. If the
+server file has changed, or if replacement text is missing or ambiguous, the
+server returns a structured `409` response with the current hash, relevant
+server text, rejected intent, reason, and suggested next action.
+
 When future merge flows need human review, TMLBrain should create conflict
 packages under `.tmlbrain/conflicts/` instead of dropping the user into raw Git
 conflict markers.
 
+The CLI now creates those packages for API `409` responses and refreshes the
+local snapshot when possible.
+
 Conflict packages contain:
 
 - conflict id;
@@ -72,8 +92,8 @@ Recommended MVP server layout:
 
 The server API should run from `/srv/tmlbrain-worktree`. After an accepted
 write request, the server commits in the worktree and pushes to
-`/srv/tmlbrain.git`. Backup to the dedicated knowledge repository is a separate
-server-side job.
+`/srv/tmlbrain.git`, then attempts to push the accepted commit to the
+dedicated knowledge repository backup remote.
 
 Recommended Docker server layout:
 
@@ -102,7 +122,7 @@ Use:
 
 ```text
 tmlbrain config show
-tmlbrain config set-server http://server-host:7389 --token <token>
+tmlbrain config set-server http://server-host:8477 --token <token>
 tmlbrain sync --pull
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@time-machine-lab/tmlbrain",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "TMLBrain local-first team knowledge base tooling.",
   "type": "commonjs",
   "bin": {
@@ -19,6 +19,8 @@
     "tmlbrain": "node bin/tmlbrain.js",
     "validate": "node bin/tmlbrain.js validate",
     "index": "node bin/tmlbrain.js index",
+    "graph:index": "node bin/tmlbrain.js graph index --json",
+    "graph:query": "node bin/tmlbrain.js graph query \"knowledge\" --json",
     "test": "node bin/tmlbrain.js validate && node bin/tmlbrain.js index --json"
   },
   "engines": {

package/scripts/backup/scheduled-backup.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env sh
+set -eu
+
+INTERVAL="${TMLBRAIN_BACKUP_INTERVAL_SECONDS:-0}"
+REMOTE="${TMLBRAIN_BACKUP_REMOTE:-backup}"
+WORKTREE="${TMLBRAIN_WORKTREE:-${TMLBRAIN_DATA_DIR:-/data}/worktree}"
+APP_DIR="${TMLBRAIN_APP_DIR:-/app}"
+
+case "$INTERVAL" in
+  ''|*[!0-9]*)
+    echo "TMLBRAIN_BACKUP_INTERVAL_SECONDS must be a positive integer." >&2
+    exit 2
+    ;;
+esac
+
+if [ "$INTERVAL" -le 0 ]; then
+  echo "TMLBrain scheduled backup disabled."
+  exit 0
+fi
+
+while :; do
+  sleep "$INTERVAL"
+  if [ ! -d "$WORKTREE/.git" ]; then
+    echo "TMLBrain scheduled backup skipped: $WORKTREE is not a Git worktree." >&2
+    continue
+  fi
+  echo "Running scheduled TMLBrain backup to $REMOTE."
+  (
+    cd "$WORKTREE"
+    node "$APP_DIR/bin/tmlbrain.js" backup --remote "$REMOTE"
+  ) || echo "Scheduled TMLBrain backup failed." >&2
+done

package/scripts/backup/tmlbrain-backup.service

@@ -0,0 +1,9 @@
+[Unit]
+Description=TMLBrain scheduled knowledge backup
+Wants=network-online.target
+After=network-online.target
+
+[Service]
+Type=oneshot
+WorkingDirectory=/data/worktree
+ExecStart=/usr/bin/node /app/bin/tmlbrain.js backup --remote backup

package/scripts/backup/tmlbrain-backup.timer

@@ -0,0 +1,10 @@
+[Unit]
+Description=Run TMLBrain knowledge backup periodically
+
+[Timer]
+OnBootSec=5min
+OnUnitActiveSec=15min
+Persistent=true
+
+[Install]
+WantedBy=timers.target