@time-machine-lab/tmlbrain 0.1.0

package/docs/spikes/cocoindex-local-indexing.md

@@ -0,0 +1,31 @@
+# CocoIndex Local Indexing Spike
+
+## Purpose
+
+Evaluate CocoIndex as the preferred local incremental indexing pipeline for Markdown knowledge documents.
+
+## Fit
+
+CocoIndex matches the TMLBrain indexing role because it is designed around data transformation and indexing pipelines. For TMLBrain, it should scan `knowledge/**/*.md`, parse front matter and Markdown structure, detect changed files, and maintain derived local indexes without requiring a full manual rebuild for every edit.
+
+## Proposed Pipeline
+
+```text
+knowledge/**/*.md
+  -> file path, mtime, sha256
+  -> front matter
+  -> headings
+  -> chunks
+  -> explicit links
+  -> local index artifacts
+```
+
+## MVP Decision
+
+The core CLI implements a deterministic dependency-light index first. CocoIndex remains the preferred graph runtime pipeline and is activated through optional graph setup so core sync does not depend on Python.
+
+## Open Follow-ups
+
+- Choose exact local storage for CocoIndex outputs.
+- Validate install behavior on Windows.
+- Confirm incremental update behavior with moved files.

package/docs/spikes/lightrag-retrieval.md

@@ -0,0 +1,27 @@
+# LightRAG Retrieval Spike
+
+## Purpose
+
+Evaluate LightRAG as the preferred local graph and semantic retrieval layer for TMLBrain.
+
+## Fit
+
+LightRAG matches the retrieval role because it combines chunk retrieval with graph-enhanced context. For TMLBrain, it should sit above deterministic Markdown indexing and use local chunks plus explicit graph context before adding LLM-extracted entity and relation edges.
+
+## MVP Decision
+
+LightRAG is optional in the default install. Exact search and deterministic graph search must continue to work when LightRAG, model credentials, or local model resources are unavailable.
+
+## Retrieval Order
+
+```text
+exact search
+  -> deterministic metadata/link graph
+  -> LightRAG graph/semantic retrieval
+```
+
+## Open Follow-ups
+
+- Decide local model vs cloud API for embeddings.
+- Choose where LightRAG state is stored under `.tmlbrain/index/`.
+- Define how Skill cites source documents and chunks returned by LightRAG.

package/docs/sync.md

@@ -0,0 +1,110 @@
+# Server-Owned Sync
+
+## User-Facing Model
+
+Users ask TMLBrain to refresh their local read-only snapshot:
+
+```text
+tmlbrain sync --pull
+```
+
+Users ask TMLBrain to write knowledge through the server:
+
+```text
+tmlbrain save --title "Title" --content "Content"
+tmlbrain save ./note.md
+tmlbrain remote update --file knowledge/00-inbox/note.md --replace "old" --with "new"
+```
+
+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.
+
+## Internal Model
+
+TMLBrain uses Git only on the server write path:
+
+```text
+client local snapshot
+  <- HTTP snapshot
+  <- TMLBrain server API
+
+client write request
+  -> TMLBrain server API
+  -> server worktree Markdown mutation
+  -> server validation
+  -> server Git commit
+  -> server bare repository
+  -> dedicated knowledge repository backup
+```
+
+## Conflict Handling
+
+When the server cannot apply a requested update safely, it rejects the request
+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.
+
+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.
+
+Conflict packages contain:
+
+- conflict id;
+- file path;
+- reason;
+- base content when available;
+- local content or local patch;
+- remote content or remote status;
+- next actions.
+
+The Skill reads the package, explains the conflict in normal language, and proposes a merged Markdown result for user confirmation.
+
+## Server Topology
+
+Recommended MVP server layout:
+
+```text
+/srv/tmlbrain.git          bare repository, operational main copy
+/srv/tmlbrain-worktree     checked-out worktree for publishing and backup jobs
+```
+
+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.
+
+Recommended Docker server layout:
+
+```text
+/data/worktree      checked-out worktree used by the server API
+/data/tmlbrain.git  local bare repository used by the server
+```
+
+The TMLBrain Docker image contains tooling and templates only. Real knowledge
+should live in a dedicated knowledge repository configured with
+`TMLBRAIN_KNOWLEDGE_REPO`. On first boot:
+
+1. existing `/data/worktree` is reused;
+2. otherwise `TMLBRAIN_KNOWLEDGE_REPO` is cloned into `/data/worktree`;
+3. otherwise the server initializes a template-only skeleton.
+
+If `TMLBRAIN_KNOWLEDGE_REPO` is set but the cloned repository does not contain
+`knowledge/`, server startup fails instead of silently creating an empty
+knowledge base.
+
+## Client Configuration
+
+Client server configuration lives in `.tmlbrain/state.json`.
+
+Use:
+
+```text
+tmlbrain config show
+tmlbrain config set-server http://server-host:7389 --token <token>
+tmlbrain sync --pull
+```
+
+The config command reports whether a token exists, but it does not print the
+token value.

package/knowledge/README.md

@@ -0,0 +1,71 @@
+---
+title: Knowledge Folder Rules
+type: reference
+status: active
+owner: TML
+tags: []
+updated: 2026-06-17
+---
+
+# Knowledge Folder
+
+This folder stores the team's maintained knowledge documents.
+
+## Structure
+
+- `00-inbox/`: temporary notes waiting to be classified.
+- `10-projects/`: project-specific documents, plans, decisions, and retrospectives.
+- `20-areas/`: long-lived responsibility areas such as product, operations, engineering, brand, and business domains.
+- `30-resources/`: reusable research, methods, notes, external references, and learning material.
+- `40-references/`: stable reference material such as API notes, configuration, accounts, checklists, standards, and glossaries.
+- `90-archive/`: inactive or historical documents kept for future search and traceability.
+- `_templates/`: reusable Markdown templates for new documents.
+
+User-facing requests such as "archive this to the knowledge base", "save
+this", or "store this" mean the content should be saved into TMLBrain, normally
+under `00-inbox/` first. Use `90-archive/` only for inactive historical content.
+
+## Document Rules
+
+Use Markdown by default. `00-inbox/` is intentionally low-friction and can hold incomplete notes. Documents outside `00-inbox/` are managed knowledge and must start with metadata:
+
+```markdown
+---
+title: Document title
+type: project | area | resource | reference | meeting | decision
+owner: Team or person
+status: draft | active | stale | archived
+updated: YYYY-MM-DD
+tags: []
+---
+```
+
+Allowed `type` values:
+
+- `project`: project plans, decisions, roadmaps, retrospectives, and project knowledge.
+- `area`: durable team responsibility areas and operating domains.
+- `resource`: reusable methods, research, notes, and external learning material.
+- `reference`: stable facts, configuration, APIs, accounts, standards, and checklists.
+- `meeting`: meeting records and summaries.
+- `decision`: decisions with context and consequences.
+
+Allowed `status` values:
+
+- `draft`: incomplete or being shaped.
+- `active`: current and expected to be useful.
+- `stale`: retained and searchable, but likely needs review.
+- `archived`: inactive but intentionally kept.
+
+Documents in `90-archive/` must use `status: archived`. An archive reason is optional; retaining knowledge does not require a justification.
+
+Prefer short, focused documents. If a document grows too large, split it by
+topic and link related documents together.
+
+## Maintenance Flow
+
+1. Capture rough or unclassified material in `00-inbox/`.
+2. Promote durable material into the folder that best describes its future use.
+3. Keep metadata current enough for local indexing and AI filtering.
+4. Use Markdown links or wiki links to connect related documents.
+5. Mark stale content as `status: stale` instead of deleting it.
+6. Move inactive content to `90-archive/` when it should stay searchable but no longer appears in active areas.

package/knowledge/_templates/area.md

@@ -0,0 +1,18 @@
+---
+title: Area name
+type: area
+status: draft
+owner: TML
+tags: []
+updated: YYYY-MM-DD
+---
+
+# Area name
+
+## Scope
+
+## Operating Rules
+
+## Related Projects
+
+## Review Notes

package/knowledge/_templates/decision.md

@@ -0,0 +1,18 @@
+---
+title: Decision title
+type: decision
+status: draft
+owner: TML
+tags: []
+updated: YYYY-MM-DD
+---
+
+# Decision title
+
+## Context
+
+## Decision
+
+## Consequences
+
+## Review

package/knowledge/_templates/meeting.md

@@ -0,0 +1,18 @@
+---
+title: Meeting title
+type: meeting
+status: draft
+owner: TML
+tags: []
+updated: YYYY-MM-DD
+---
+
+# Meeting title
+
+## Context
+
+## Discussion
+
+## Decisions
+
+## Follow-ups

package/knowledge/_templates/project.md

@@ -0,0 +1,18 @@
+---
+title: Project name
+type: project
+status: draft
+owner: TML
+tags: []
+updated: YYYY-MM-DD
+---
+
+# Project name
+
+## Purpose
+
+## Current State
+
+## Decisions
+
+## Open Questions

package/knowledge/_templates/reference.md

@@ -0,0 +1,18 @@
+---
+title: Reference title
+type: reference
+status: draft
+owner: TML
+tags: []
+updated: YYYY-MM-DD
+---
+
+# Reference title
+
+## Facts
+
+## Usage
+
+## Constraints
+
+## Related Knowledge

package/knowledge/_templates/resource.md

@@ -0,0 +1,18 @@
+---
+title: Resource title
+type: resource
+status: draft
+owner: TML
+tags: []
+updated: YYYY-MM-DD
+---
+
+# Resource title
+
+## Summary
+
+## Details
+
+## Links
+
+## Related Knowledge

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@time-machine-lab/tmlbrain",
+  "version": "0.1.0",
+  "description": "TMLBrain local-first team knowledge base tooling.",
+  "type": "commonjs",
+  "bin": {
+    "tmlbrain": "bin/tmlbrain.js"
+  },
+  "files": [
+    "bin/",
+    "docs/",
+    "knowledge/README.md",
+    "knowledge/_templates/",
+    "scripts/",
+    "skills/",
+    "README.md"
+  ],
+  "scripts": {
+    "tmlbrain": "node bin/tmlbrain.js",
+    "validate": "node bin/tmlbrain.js validate",
+    "index": "node bin/tmlbrain.js index",
+    "test": "node bin/tmlbrain.js validate && node bin/tmlbrain.js index --json"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Time-Machine-Lab/TMLBrain.git"
+  },
+  "keywords": [
+    "tmlbrain",
+    "knowledge-base",
+    "ai-skill",
+    "markdown"
+  ],
+  "license": "UNLICENSED"
+}

package/scripts/README.md

@@ -0,0 +1,12 @@
+# Scripts
+
+This folder contains automation wrappers for TMLBrain.
+
+- `install/`: client bootstrap wrappers for Windows and macOS/Linux. They call `tmlbrain client install`.
+- `sync/`: server-side Git hook templates for legacy/non-Docker deployments.
+- `index/`: search index, metadata extraction, and knowledge graph generation.
+- `backup/`: scheduled server-to-dedicated-knowledge-repository backup wrappers.
+- `docker/`: server container entrypoint.
+- `release/`: commit-message release instruction parsing for the auto-release workflow.
+
+Scripts should support dry-run mode before modifying remote data.

package/scripts/backup/server-to-github.ps1

@@ -0,0 +1,20 @@
+param(
+  [string]$Remote = "backup",
+  [switch]$DryRun
+)
+
+$ErrorActionPreference = "Stop"
+$root = Resolve-Path (Join-Path $PSScriptRoot "..\..")
+$argsList = @("backup", "--remote", $Remote)
+
+if ($DryRun) {
+  $argsList += "--dry-run"
+}
+
+Push-Location $root
+try {
+  node ".\bin\tmlbrain.js" @argsList
+}
+finally {
+  Pop-Location
+}

package/scripts/backup/server-to-github.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env sh
+set -eu
+
+ROOT="$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)"
+REMOTE="${TMLBRAIN_BACKUP_REMOTE:-backup}"
+DRY_RUN=""
+
+if [ "${1:-}" = "--dry-run" ]; then
+  DRY_RUN="--dry-run"
+fi
+
+cd "$ROOT"
+node "./bin/tmlbrain.js" backup --remote "$REMOTE" $DRY_RUN

package/scripts/docker/server-entrypoint.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env sh
+set -eu
+
+if [ -z "${TMLBRAIN_SERVER_TOKEN:-}" ]; then
+  echo "TMLBRAIN_SERVER_TOKEN is required for the TMLBrain server container." >&2
+  exit 1
+fi
+
+DATA_DIR="${TMLBRAIN_DATA_DIR:-/data}"
+WORKTREE="${TMLBRAIN_WORKTREE:-$DATA_DIR/worktree}"
+BARE_REPO="${TMLBRAIN_BARE_REPO:-$DATA_DIR/tmlbrain.git}"
+KNOWLEDGE_REPO="${TMLBRAIN_KNOWLEDGE_REPO:-}"
+KNOWLEDGE_REF="${TMLBRAIN_KNOWLEDGE_REF:-main}"
+HOST="${TMLBRAIN_HOST:-0.0.0.0}"
+PORT="${TMLBRAIN_PORT:-7389}"
+
+mkdir -p "$DATA_DIR"
+
+if [ ! -d "$WORKTREE/.git" ]; then
+  if [ -d "$BARE_REPO" ]; then
+    echo "Restoring TMLBrain worktree from existing local bare repository."
+    git clone "$BARE_REPO" "$WORKTREE"
+  elif [ -n "$KNOWLEDGE_REPO" ]; then
+    echo "Initializing TMLBrain knowledge from $KNOWLEDGE_REPO ($KNOWLEDGE_REF)."
+    git clone --branch "$KNOWLEDGE_REF" "$KNOWLEDGE_REPO" "$WORKTREE"
+    cd "$WORKTREE"
+    git remote rename origin backup
+  else
+    echo "No TMLBRAIN_KNOWLEDGE_REPO configured. Initializing template-only knowledge skeleton."
+    mkdir -p "$WORKTREE"
+    cp -R /app/knowledge "$WORKTREE/knowledge"
+    cd "$WORKTREE"
+    git init -b main
+  fi
+fi
+
+cd "$WORKTREE"
+
+if [ ! -d .git ]; then
+  git init -b main
+fi
+
+if [ ! -d knowledge ]; then
+  if [ -n "$KNOWLEDGE_REPO" ]; then
+    echo "Knowledge repository must contain a knowledge/ directory." >&2
+    exit 1
+  fi
+  cp -R /app/knowledge "$WORKTREE/knowledge"
+fi
+
+git config user.name "${TMLBRAIN_GIT_USER_NAME:-TMLBrain Server}"
+git config user.email "${TMLBRAIN_GIT_USER_EMAIL:-tmlbrain@localhost}"
+
+if [ -n "$KNOWLEDGE_REPO" ]; then
+  if git remote get-url backup >/dev/null 2>&1; then
+    git remote set-url backup "$KNOWLEDGE_REPO"
+  else
+    git remote add backup "$KNOWLEDGE_REPO"
+  fi
+fi
+
+if ! git rev-parse --verify HEAD >/dev/null 2>&1; then
+  git add knowledge
+  git commit -m "Initialize TMLBrain knowledge"
+fi
+
+if [ ! -d "$BARE_REPO" ]; then
+  git clone --bare "$WORKTREE" "$BARE_REPO"
+fi
+
+if git remote get-url origin >/dev/null 2>&1; then
+  git remote set-url origin "$BARE_REPO"
+else
+  git remote add origin "$BARE_REPO"
+fi
+
+git add knowledge
+if ! git diff --cached --quiet; then
+  git commit -m "Initialize TMLBrain knowledge"
+fi
+
+git push -u origin HEAD:main >/dev/null 2>&1 || true
+
+exec node /app/bin/tmlbrain.js serve --host "$HOST" --port "$PORT"

package/scripts/install/install.ps1

@@ -0,0 +1,44 @@
+param(
+  [string]$Server = "",
+  [string]$Token = "",
+  [switch]$Local,
+  [switch]$Graph,
+  [switch]$DryRun,
+  [switch]$Yes
+)
+
+$ErrorActionPreference = "Stop"
+$root = Resolve-Path (Join-Path $PSScriptRoot "..\..")
+$argsList = @("client", "install")
+
+if ($Server -ne "") {
+  $argsList += @("--server", $Server)
+}
+
+if ($Token -ne "") {
+  $argsList += @("--token", $Token)
+}
+
+if ($Local) {
+  $argsList += "--local"
+}
+
+if ($Graph) {
+  $argsList += "--graph"
+}
+
+if ($DryRun) {
+  $argsList += "--dry-run"
+}
+
+if ($Yes) {
+  $argsList += "--yes"
+}
+
+Push-Location $root
+try {
+  node ".\bin\tmlbrain.js" @argsList
+}
+finally {
+  Pop-Location
+}

package/scripts/install/install.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env sh
+set -eu
+
+ROOT="$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)"
+ARGS="client install"
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --server)
+      ARGS="$ARGS --server $2"
+      shift 2
+      ;;
+    --token)
+      ARGS="$ARGS --token $2"
+      shift 2
+      ;;
+    --local)
+      ARGS="$ARGS --local"
+      shift
+      ;;
+    --graph)
+      ARGS="$ARGS --graph"
+      shift
+      ;;
+    --dry-run)
+      ARGS="$ARGS --dry-run"
+      shift
+      ;;
+    --yes)
+      ARGS="$ARGS --yes"
+      shift
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+cd "$ROOT"
+node "./bin/tmlbrain.js" $ARGS