@time-machine-lab/tmlbrain 0.1.0

package/docs/architecture.md

@@ -0,0 +1,84 @@
+# TMLBrain Architecture
+
+## Storage Layers
+
+```text
+Local Snapshot <- Server Knowledge Base -> Dedicated Knowledge Repo
+        |                   |
+        |                   +-> Optional Online Reader
+        |
+        +-> AI Search Skill / Server Write Requests
+```
+
+The TMLBrain tool repository and the team knowledge repository are separate.
+The tool repository contains CLI code, Docker packaging, Skill instructions,
+docs, templates, and release workflows. Real team knowledge lives in a
+dedicated Git repository that contains `knowledge/` at its root.
+
+## Local Snapshot
+
+The local snapshot is optimized for fast reading, searching, indexing, and AI
+retrieval. Users and AI agents work against the local copy for search, then
+request server-side writes when knowledge must change. Clients do not mutate the
+remote Git repository and do not need Git in the HTTP-only workflow.
+
+## Server Knowledge Base
+
+The server copy is the shared operational source. It receives write requests
+through the TMLBrain server API, mutates Markdown, validates the knowledge base,
+commits repository changes, and is periodically backed up to the dedicated
+knowledge repository.
+
+In Docker deployments, the server stores runtime data under the mounted
+`/data` volume:
+
+```text
+/data/worktree      server worktree used by the API
+/data/tmlbrain.git  local bare repository used by the server
+```
+
+On first boot, if `/data/worktree` does not exist and
+`TMLBRAIN_KNOWLEDGE_REPO` is configured, the server clones that dedicated
+knowledge repository instead of starting from an empty knowledge base.
+
+## Dedicated Knowledge Repository
+
+The dedicated knowledge repository is used for first-boot restore, disaster
+recovery, version history, and reviewable snapshots. It is not the primary
+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.
+
+## Release Workflow
+
+The npm client package, Docker server image, and server deployment are handled
+by one main-branch workflow, `.github/workflows/auto-release.yml`. The workflow
+reads the HEAD commit message and only releases when `<Auto>` is present.
+
+The commit message provides:
+
+- `-v:<semver>` for both npm and Docker versions;
+- `-rp:<port>` for the Docker image default server port;
+- optional `-de:<...>` runtime Docker metadata in the commit message.
+
+The workflow does not commit release logs back to the repository. Maintainers
+can update `prod_deploy.log` manually before committing an auto-release
+instruction when they want an explicit production release trail.
+
+Docker publishing uses `DOCKER_USERNAME`, `DOCKER_PASSWORD`, and `DOCKER_REPO`.
+After pushing the image, the workflow logs in to the configured server with
+`SERVER_HOST`, `SERVER_USER`, and `SERVER_PWD`, pulls the new image, and
+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`.
+
+## Search And Graph Layer
+
+The first implementation can combine:
+
+- full-text search over Markdown files;
+- metadata search using front matter;
+- backlink extraction from Markdown links;
+- later semantic embeddings for natural-language retrieval.

package/docs/backup.md

@@ -0,0 +1,76 @@
+# Backup And Recovery
+
+## Backup Role
+
+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.
+
+If TMLBrain must upload modified server knowledge back to GitHub, the running
+server needs write authorization for the dedicated knowledge repository. GitHub
+will not accept anonymous pushes, even if the repository is public. A public
+repository may allow unauthenticated clone/read, but push/backup still requires
+a credential.
+
+Recommended credential option:
+
+- GitHub token with repository write permission, injected as a runtime secret.
+  Fine-grained tokens are preferred; classic tokens also work with the right
+  scope: use `repo` for private repositories, or `public_repo` only for public
+  repositories. Use it with HTTPS repository URLs such as
+  `https://github.com/org/repo.git`.
+
+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`.
+
+The auto-release workflow supports this deployment pattern with:
+
+```text
+TMLBRAIN_KNOWLEDGE_REPO
+TMLBRAIN_KNOWLEDGE_TOKEN
+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.
+
+## Dry Run
+
+Use:
+
+```text
+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`.
+
+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.
+
+## Recovery
+
+For Docker deployments, first-boot restore can be handled by:
+
+```text
+TMLBRAIN_KNOWLEDGE_REPO=https://github.com/Time-Machine-Lab/TMLBrainKnowledge.git
+```
+
+If `/data/worktree` is missing, the container clones that repository. If the
+mounted data volume already contains `/data/worktree`, the server reuses it and
+does not overwrite it.
+
+To recover a failed non-Docker server:
+
+1. Provision a new server with Git.
+2. Clone the dedicated knowledge repository as a bare repository.
+3. Recreate the server worktree from the bare repository.
+4. Reconfigure TMLBrain clients to use the new server remote.
+5. Run `tmlbrain sync` from clients to refresh local state.

package/docs/decisions/.gitkeep

@@ -0,0 +1 @@
+

package/docs/decisions/0001-core-runtime.md

@@ -0,0 +1,18 @@
+# 0001 Core Runtime Choice
+
+## Decision
+
+Use a dependency-light Node CLI for the TMLBrain core runtime.
+
+## Rationale
+
+The default user path must support npm/npx client install, validation, exact search, document creation, read-only snapshot synchronization, server API write requests, conflict-aware retries, backup dry-runs, and Skill command recipes without requiring Python.
+
+Node is already available in the TmlUs/Codex workflow used by this project, and the core CLI can rely on built-in Node modules plus external Git. Python remains optional and is activated only for graph retrieval features such as CocoIndex and LightRAG.
+
+## Consequences
+
+- Core TMLBrain remains usable immediately after default client installation.
+- HTTP-only clients do not require Git; Git remains a server, backup, or legacy migration dependency.
+- CocoIndex and LightRAG are graph-runtime enhancements, not core sync dependencies.
+- Markdown parsing is intentionally simple in the MVP and can be replaced with a structured parser later.

package/docs/fixtures/knowledge-sample/alpha-reference.md

@@ -0,0 +1,14 @@
+---
+title: Alpha Reference
+type: reference
+status: active
+owner: TML
+tags: [alpha, reference]
+updated: 2026-06-16
+---
+
+# Alpha Reference
+
+## Facts
+
+This fixture is used to validate exact search, metadata extraction, and backlink generation.

package/docs/fixtures/knowledge-sample/project-alpha.md

@@ -0,0 +1,18 @@
+---
+title: Project Alpha
+type: project
+status: active
+owner: TML
+tags: [alpha]
+updated: 2026-06-16
+---
+
+# Project Alpha
+
+## Purpose
+
+Project Alpha validates local indexing, deterministic graph extraction, and retrieval behavior.
+
+## Links
+
+See [Alpha Reference](alpha-reference.md) and [[Operations Area]].

package/docs/fixtures/patches/update-alpha-reference.patch

@@ -0,0 +1,9 @@
+diff --git a/docs/fixtures/knowledge-sample/alpha-reference.md b/docs/fixtures/knowledge-sample/alpha-reference.md
+--- a/docs/fixtures/knowledge-sample/alpha-reference.md
++++ b/docs/fixtures/knowledge-sample/alpha-reference.md
+@@ -12,4 +12,4 @@ updated: 2026-06-16
+ 
+ ## Facts
+ 
+-This fixture is used to validate exact search, metadata extraction, and backlink generation.
++This fixture validates exact search, metadata extraction, and backlink generation.

package/docs/indexing.md

@@ -0,0 +1,32 @@
+# Local Indexing And Retrieval
+
+## Layers
+
+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.
+
+## Deterministic Index
+
+`tmlbrain index` writes local artifacts under `.tmlbrain/index/`:
+
+- `documents.json`: file path, metadata, headings, hashes, and timestamps.
+- `chunks.json`: heading-based chunks with line ranges and hashes.
+- `graph.json`: deterministic links, tags, owner, and status edges.
+- `manifest.json`: index summary and degraded-mode status.
+
+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.
+
+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.

package/docs/install.md

@@ -0,0 +1,166 @@
+# TMLBrain Install
+
+## Client
+
+Recommended interactive install:
+
+```text
+npx @time-machine-lab/tmlbrain client install
+```
+
+The installer asks for:
+
+- server URL, optional;
+- server token, only when a server URL is provided;
+- optional graph runtime setup.
+
+Leave the server URL empty to start in local-only mode. Local-only clients can
+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 sync --pull
+```
+
+Non-interactive client install:
+
+```text
+npx @time-machine-lab/tmlbrain client install --server http://server-host:7389 --token <token> --yes
+```
+
+Global install is also supported after the npm package is published:
+
+```text
+npm install -g @time-machine-lab/tmlbrain
+tmlbrain client install
+```
+
+## Server
+
+The server is installed separately and should run in Docker. The token is
+required. Team deployments should also provide `TMLBRAIN_KNOWLEDGE_REPO` so the
+server restores the real knowledge base instead of starting from a template-only
+skeleton.
+
+```text
+docker run -d --name tmlbrain-server \
+  -p 7389:7389 \
+  -e TMLBRAIN_SERVER_TOKEN=<required-token> \
+  -e TMLBRAIN_KNOWLEDGE_REPO=https://github.com/Time-Machine-Lab/TMLBrainKnowledge.git \
+  -e TMLBRAIN_KNOWLEDGE_REF=main \
+  -v tmlbrain-data:/data \
+  <DOCKER_REPO>:latest
+```
+
+Compose:
+
+```text
+TMLBRAIN_SERVER_TOKEN=<required-token> docker compose up -d
+```
+
+The container initializes or reuses:
+
+```text
+/data/worktree      server worktree used by the API
+/data/tmlbrain.git  server bare repository
+```
+
+## Dedicated Knowledge Repository
+
+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
+```
+
+That repository must contain the TMLBrain `knowledge/` directory at its root.
+On first server boot:
+
+1. If `/data/worktree` already exists, the container reuses it.
+2. Else if `TMLBRAIN_KNOWLEDGE_REPO` is configured, the container clones that
+   repository and registers it as the `backup` remote.
+3. Else the container initializes a template-only skeleton for development or
+   blank starts.
+
+The image is published by `.github/workflows/auto-release.yml` to the Docker
+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.
+
+```text
+<DOCKER_REPO>:latest
+<DOCKER_REPO>:<version>
+<DOCKER_REPO>:v<version>
+```
+
+Required GitHub Actions secrets:
+
+```text
+NPM_TOKEN
+DOCKER_USERNAME
+DOCKER_PASSWORD
+DOCKER_REPO
+SERVER_HOST
+SERVER_USER
+SERVER_PWD
+TMLBRAIN_SERVER_TOKEN
+```
+
+Knowledge repository secrets for private GitHub backup/restore:
+
+```text
+TMLBRAIN_KNOWLEDGE_REPO
+TMLBRAIN_KNOWLEDGE_TOKEN
+TMLBRAIN_KNOWLEDGE_REF
+```
+
+`TMLBRAIN_KNOWLEDGE_REPO` must be an HTTPS URL, for example
+`https://github.com/Time-Machine-Lab/TMLBrainKnowledge.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
+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.
+
+## Release Command Format
+
+Releases are driven by the HEAD commit message on `main`. The workflow skips
+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>
+```
+
+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
+  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
+  not baked as a secret into the image.
+
+The workflow does not update repository files. If maintainers want a production
+release trail, update `prod_deploy.log` manually in the same local change set
+before committing the auto-release instruction. Before publishing artifacts,
+the workflow runs tests. If the requested npm version already exists, npm
+publishing is skipped so Docker image publishing and server deployment can be
+retried with the same release commit.
+
+## Runtime Split
+
+- Clients use npm/npx and only need Node.
+- Clients may run local-only without a server.
+- Team sync and writes require a server URL and token.
+- Servers use Docker and require `TMLBRAIN_SERVER_TOKEN`.
+- Git and dedicated knowledge repository credentials belong to the server side,
+  not clients.

package/docs/roadmap.md

@@ -0,0 +1,27 @@
+# Roadmap
+
+## Phase 1: Project Foundation
+
+- Create repository structure.
+- Define knowledge folder rules.
+- Define AI skill responsibilities.
+- Decide sync direction and conflict policy.
+
+## Phase 2: Sync And Backup
+
+- Add local-to-server sync script.
+- Add server-to-local refresh script.
+- Add scheduled server-to-dedicated-knowledge-repository backup script.
+- Add dry-run and conflict detection.
+
+## Phase 3: Retrieval
+
+- Add Markdown full-text search.
+- Add metadata index.
+- Add document relation graph.
+- Add optional semantic search.
+
+## Phase 4: Online Reading
+
+- Generate a static reading site from `knowledge/`.
+- Optionally sync selected documents to Feishu for team browsing.

package/docs/runtime.md

@@ -0,0 +1,95 @@
+# TMLBrain Runtime
+
+## Goal
+
+TMLBrain should feel like one product to the user:
+
+```text
+npx @time-machine-lab/tmlbrain client install
+@TMLBrain search or update knowledge
+```
+
+Git, indexing, patches, and conflict handling are implementation details hidden
+behind TMLBrain CLI, server API, MCP tools, and Skill instructions.
+
+## Core Runtime
+
+The core runtime must work without Python:
+
+- TMLBrain CLI.
+- TMLBrain Skill registration.
+- Local workspace state under `.tmlbrain/`.
+- Exact search.
+- Markdown validation.
+- Document creation.
+- Server API write requests.
+- Read-only snapshot sync.
+
+HTTP-only clients do not require Git. Git detection/provisioning belongs to the
+server runtime and legacy migration flows.
+
+## Optional Graph Runtime
+
+CocoIndex and LightRAG are optional graph retrieval features. They are enabled by:
+
+```text
+tmlbrain graph setup
+```
+
+If Python, CocoIndex, or LightRAG cannot be activated, core TMLBrain remains usable in degraded search mode.
+
+## Installer Entry Points
+
+Recommended npm client entry:
+
+```text
+npx @time-machine-lab/tmlbrain client install
+```
+
+The client installer asks for a server URL. Leaving it empty starts local-only
+mode; providing a server URL also asks for the server token.
+
+Windows:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts/install/install.ps1
+```
+
+macOS/Linux:
+
+```sh
+sh scripts/install/install.sh
+```
+
+Both scripts call the same CLI bootstrap flow and keep the user away from raw Git commands.
+
+Non-interactive client install:
+
+```text
+npx @time-machine-lab/tmlbrain client install --server http://server-host:7389 --token secret --yes
+```
+
+## Server Runtime
+
+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
+```
+
+The image contains tooling and templates only. Real knowledge is restored from
+`TMLBRAIN_KNOWLEDGE_REPO` on first boot or reused from the mounted data volume.
+Released images get their default `TMLBRAIN_PORT` from the `-rp` value in the
+`<Auto>` release commit message. Runtime deployments can still override the
+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
+```
+
+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.

package/docs/server-api.md

@@ -0,0 +1,120 @@
+# TMLBrain Server API
+
+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.
+
+## Run The Server
+
+Recommended Docker deployment:
+
+```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
+```
+
+`TMLBRAIN_KNOWLEDGE_REPO` points at the dedicated knowledge repository. If the
+data volume already contains `/data/worktree`, the container reuses that
+worktree instead of cloning again.
+
+Run from the server worktree:
+
+```text
+node bin/tmlbrain.js serve --host 0.0.0.0 --port 7389
+```
+
+Optional token protection:
+
+```text
+TMLBRAIN_SERVER_TOKEN=secret node bin/tmlbrain.js serve --host 0.0.0.0 --port 7389
+```
+
+Clients then install with:
+
+```text
+npx @time-machine-lab/tmlbrain client install --server http://server-host:7389 --token secret --yes
+```
+
+The client stores this in `.tmlbrain/state.json`. The token is not shown by
+normal config commands.
+
+Show the active client server:
+
+```text
+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 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
+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
+```
+
+## Client Commands
+
+Pull a read-only snapshot:
+
+```text
+node bin/tmlbrain.js sync --pull
+```
+
+Search locally:
+
+```text
+node bin/tmlbrain.js find "keyword"
+```
+
+Save text through the server:
+
+```text
+node bin/tmlbrain.js save --title "Title" --content "Content"
+```
+
+Save a local file through the server:
+
+```text
+node bin/tmlbrain.js save ./note.md
+```
+
+Ask the server to update a precise text region:
+
+```text
+node bin/tmlbrain.js remote update --file knowledge/00-inbox/note.md --replace "old text" --with "new text"
+```
+
+## 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.
+
+## 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`.
+
+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
+dedicated knowledge repository backup jobs.