@time-machine-lab/tmlbrain 0.1.0 → 0.1.2

package/README.md

@@ -19,7 +19,7 @@ TMLBrain keeps three coordinated copies of the knowledge base:
 - Maintain a clean folder structure for documents.
 - Let AI search local snapshots and request server-side precise Markdown updates.
 - Pull read-only local snapshots from the server copy.
-- Back up the server copy to GitHub on a server-side schedule.
+- Back up accepted server writes to GitHub from the server side.
 - Build an optional online reading layer later.
 
 ## Repository Layout
@@ -34,40 +34,66 @@ TMLBrain/
   docs/                   Architecture, decisions, and operating docs.
 ```
 
-## Local Tooling
+## Client Install
 
-The npm package exposes a dependency-light CLI:
+Recommended npm install:
+
+```text
+npm install -g @time-machine-lab/tmlbrain@latest
+tmlbrain client install
+```
+
+The installer asks for a server URL. Leave it empty to start in local-only
+mode, or provide the TMLBrain server URL and token to enable team sync and
+server-side writes.
+
+Non-interactive npm install:
+
+```text
+npm install -g @time-machine-lab/tmlbrain@latest
+tmlbrain client install --server http://server-host:8477 --token <token> --yes
+```
+
+After installation:
 
 ```text
-npx @time-machine-lab/tmlbrain client install
 tmlbrain find "keyword"
 tmlbrain save --title "Title" --content "Content"
+tmlbrain remote update --file knowledge/30-resources/note.md --replace "old" --with "new"
+tmlbrain remote delete --file knowledge/30-resources/old-note.md
 ```
 
+Saving and archiving into the knowledge base are the same user intent:
+TMLBrain stores the content and classifies it into the approved taxonomy. It
+does not default normal saves to `knowledge/00-inbox/`; inbox is only for
+genuinely unclassified or explicitly temporary capture.
+
+Deletion is explicit: use `remote delete` only when the user really wants a
+document removed. Otherwise prefer marking content stale through `remote update`.
+
 Clients use Node for exact search and local indexing. HTTP-only clients do not
 need Git. Server-side writes use Node plus Git from the server worktree.
 Python-based CocoIndex and LightRAG support are optional graph retrieval
 enhancements.
 
-Interactive client install asks for a server URL. Leave it empty to start in
-local-only mode, or provide the TMLBrain server URL and token to enable team
-sync and server-side writes.
-
-Non-interactive client install:
+Update an existing client without re-entering the setup flow:
 
 ```text
-npx @time-machine-lab/tmlbrain client install --server http://server-host:7389 --token secret --yes
+tmlbrain update
 ```
 
+Use `npx -y @time-machine-lab/tmlbrain@latest client install` only when you
+want a one-time install without keeping a global `tmlbrain` command.
+
 ## Server Docker
 
 The server is deployed separately from clients and requires a token:
 
 ```text
 docker run -d --name tmlbrain-server \
-  -p 7389:7389 \
+  -p 8477:8477 \
   -e TMLBRAIN_SERVER_TOKEN=change-me \
-  -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
@@ -87,13 +113,13 @@ Only pushes to `main` are considered. A release runs when the HEAD commit
 message contains `<Auto>` and a version flag:
 
 ```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>
 ```
 
 - `-v` is required and becomes both the npm package version and Docker image
   version; use a Docker-compatible value such as `0.1.0` or `0.1.0-beta.1`.
 - `-rp` sets the default server port baked into the Docker image; it defaults
-  to `7389`.
+  to `8477`.
 - `-de` is optional runtime Docker argument metadata recorded in
   the commit message and may also be copied into `prod_deploy.log` manually.
 
@@ -101,6 +127,8 @@ The workflow publishes `@time-machine-lab/tmlbrain` to npm, pushes the server
 image to the Docker repository configured by `DOCKER_REPO`, and then deploys
 that image to the configured server with `SERVER_HOST`, `SERVER_USER`, and
 `SERVER_PWD`. Docker images are tagged as `latest`, `version`, and `vversion`.
+The server deploy step skips Docker login by default and directly pulls the
+public image. Only set `TMLBRAIN_SERVER_DOCKER_LOGIN=true` for private images.
 The workflow does not mutate repository files; if
 maintainers want a production release note, update `prod_deploy.log` manually
 before committing the auto-release instruction.
@@ -134,6 +162,17 @@ for private repositories, or `public_repo` only for public repositories. The
 running server needs this credential to push knowledge backups to GitHub;
 clients never need it.
 
+Optional GitHub connectivity secret:
+
+```text
+TMLBRAIN_SERVER_GIT_PROXY_URL
+```
+
+Use it only when the server cannot reach GitHub directly. The deployment applies
+the proxy to Git operations for `https://github.com` only. If this secret is not
+set but a `tmlbrain-proxy` container exists on the server, deployment uses that
+container as the Git-only proxy automatically.
+
 The Docker image contains the TMLBrain tool and knowledge templates only. Real
 team knowledge should live in a dedicated knowledge repository configured with
 `TMLBRAIN_KNOWLEDGE_REPO`. If the server volume already has `/data/worktree`,
@@ -148,5 +187,7 @@ starts.
 - Markdown is the default document format.
 - Small, precise server-side edits are preferred over whole-document rewrites.
 - Every document should have a clear owner, status, and update path.
+- Saved knowledge should be classified into the taxonomy instead of piling up
+  in inbox.
 - AI should help maintain the knowledge base instead of only searching it.
 - Clients do not push to the server repository or dedicated knowledge repository.