build: add beta distribution pipeline

Author: ktappdev

.DS_Store

@@ -0,0 +1,37 @@
+name: CI
+on:
+  push:
+  pull_request:
+  workflow_call:
+permissions:
+  contents: read
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        go: ['1.25.x', '1.26.x']
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go }}
+      - run: go test -timeout 5m ./...
+      - run: go vet ./...
+      - run: go test -race -timeout 5m ./...
+      - run: go build ./cmd/ctxt
+  analysis:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.26.x'
+      - run: go install honnef.co/go/tools/cmd/staticcheck@v0.7.0
+      - run: staticcheck ./...
+      - run: go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.10.1
+      - run: golangci-lint run
+      - run: go install golang.org/x/vuln/cmd/govulncheck@v1.1.4
+      - run: govulncheck ./...

.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: Release
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing version tag to package
+        required: true
+permissions:
+  contents: read
+jobs:
+  gate:
+    uses: ./.github/workflows/ci.yml
+  package:
+    needs: gate
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Resolve release tag
+        env:
+          REQUESTED_TAG: ${{ inputs.tag || github.ref_name }}
+        run: |
+          if ! [[ "$REQUESTED_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[A-Za-z0-9.-]+)?$ ]]; then
+            exit 1
+          fi
+          test "$(git rev-parse "$REQUESTED_TAG^{commit}")" = "$(git rev-parse HEAD)"
+          echo "RELEASE_TAG=$REQUESTED_TAG" >> "$GITHUB_ENV"
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.26.x'
+      - run: go run ./internal/dist -version "$RELEASE_TAG"
+      - name: Create draft release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$RELEASE_TAG" dist/* --verify-tag --draft --prerelease --title "$RELEASE_TAG" --notes-file CHANGELOG.md

.github/workflows/release.yml

@@ -4,3 +4,12 @@ contexting
 ctx.json
 syns.json
 /.ctxt
+/.ctxt-writer/
+/dist/
+/bin/
+/ctxt
+/ctxt.exe
+/context.json
+/context.toml
+.DS_Store
+.picode/

.gitignore

@@ -0,0 +1,10 @@
+version: "2"
+linters:
+  default: none
+  enable:
+    - govet
+    - ineffassign
+    - staticcheck
+    - unused
+run:
+  timeout: 5m

.golangci.yml

@@ -19,15 +19,16 @@ This file is for developers and AI agents working on the codebase. For user-faci
 
 ## Versioning
 
-- **Hardcoded fallback**: `main.go` line ~3: `var Version = "0.0.1"`
+- **Local fallback**: untagged direct builds report `dev`
+- **Tagged Go installs**: derive the module version from Go build metadata
 - **`make install`**: Overrides via `-ldflags "-X github.com/ktappdev/contexting.Version=..."` using `git describe --tags`
 - **Without tags**: Falls back to commit hash (e.g., `af85edb-dirty`)
 
 ### Bumping Version
 
 ```bash
 git tag v0.0.2 && make install
-ctxt version  # → 0.0.2
+ctxt version  # → 0.0.2 (ctxt --version also works)
 ```
 
 ## Project Structure
@@ -97,8 +98,9 @@ ctxt version  # → 0.0.2
 | Config format | TOML (`.ctxt/ctx_config.toml`) |
 | Output format | JSON (`.ctxt/ctx_index.json`) |
 | Atomic writes | Temp file + rename (see `io_atomic.go`) |
-| No file locking | Between processes (init vs watch can conflict) |
+| Writer guard | CLI writers are serialized per project via `.ctxt-writer/` |
 | Default model | `deepseek/deepseek-v4-flash` |
+| Supported release targets | Linux/macOS/Windows on amd64 and arm64 |
 | Synonyms | 5–12 per name |
 | Temperature | `0.9` |
 | Parallel requests | `10` |
@@ -110,7 +112,8 @@ ctxt version  # → 0.0.2
 ### Flag Defaults
 
 - `--verbose` (default: false) — gates steady-state change summaries
-- `--search-log` (default: true) — gates search query logging
+- `--llm-on-watch` (default: false) — opts into LLM calls during watch
+- `--search-log` (default: false) — gates potentially sensitive query logging
 - `--by-category` (default: true) — group bench results by category
 - `--engines` (default: `"ctxt,find,grep"`) — engines to benchmark. Also available: `fd`, `rg`, `hybrid`, `combined`
 - `--hybrid` (search flag, default: false) — enable content fallback via ripgrep when index results are sparse
@@ -132,7 +135,7 @@ Default ignores: `.venv`, `site-packages`, `__pycache__`, `node_modules`, `.env*
 ## Key Conventions for AI Agents
 
 1. **Naming — The CLI binary and command is `ctxt` (lowercase), not `contexting`. The project name is Contexting (capitalized). All user-facing command strings, error messages, help text, MCP server names, bench engine names, and doc examples MUST use `ctxt`. Only use `Contexting` when referring to the project in prose.**
-2. **Never assume file locking** — `init` and `watch` can conflict
+2. **Writer guard scope** — CLI writers are serialized locally; library callers and network filesystems require their own coordination
 3. **Atomic writes only** — use temp+rename pattern in `io_atomic.go`
 4. **Config precedence** — CLI flags > `.ctxt/ctx_config.toml` > hardcoded defaults
 5. **Config paths** — Relative paths resolve from config file location
@@ -143,6 +146,8 @@ Default ignores: `.venv`, `site-packages`, `__pycache__`, `node_modules`, `.env*
 10. **Scoring** — Exact basename +15 (highest), confidence gap truncation reduces noise
 11. **Hybrid search** — Use `--hybrid` on `search-hints` to fill gaps in index results. Ripgrep scans file contents for query tokens and merges unmatched files at score=1. Useful when the index misses files whose content literally contains the query words but whose symbols/synonyms don't connect. Add `--memory=false` if using a snapshot (non-watch) index.
 12. **`--agent` flag** — Blocks `init`/`watch`/`sync`/`clean` for safety in automated flows
+13. **Symlinks** — Entries are excluded; directory symlinks are never followed
+14. **Index size** — Initial indexing fails above 10,000 files rather than saving a partial index
 
 ## Bench Engines
 
@@ -156,4 +161,4 @@ Default ignores: `.venv`, `site-packages`, `__pycache__`, `node_modules`, `.env*
 | **hybrid** | ctxt + content fallback via ripgrep. Content matches at score=1. | When index might have blind spots. Slower (7ms avg). |
 | **combined** | Union of find + grep. Alphabetical. | Maximum recall at cost of noise. |
 
-Run: `ctxt bench --cases docs/bench_cases.json --engines ctxt,hybrid,find,grep,rg`
+Run: `ctxt bench --cases docs/bench_cases.json --engines ctxt,hybrid,find,grep,rg`

AGENTS.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 0.1.0-beta.1 — Unreleased
+
+- Consistent parent/file synonym keys during indexing and live updates.
+- Watch detects children of newly populated directories.
+- Explicit shutdown-only persistence contract; unsupported modes fail.
+- HTTPS public LLM defaults, opt-in query logs and an explicit offline mode.
+- Remote LLM endpoints require HTTPS; loopback development endpoints may use HTTP.
+- Config-aware API-key diagnostics without printing key fragments.
+- Bounded, cancellable transient HTTP retries and reported partial failures.
+- Project single-writer guard and versioned index schema.
+- File-limit failures instead of silently truncated initial indexes.
+- Symlink exclusion, bounded local HTTP requests and atomic file syncing.
+- CLI/watch/MCP regression tests and cross-platform CI.
+- Versioned platform archives, SHA-256 checksums and draft release workflow.
+
+### Upgrading
+
+Back up `.ctxt/` before upgrading. Unversioned indexes (schema 0) remain readable;
+the next save writes schema 1. Unknown newer schemas fail with an upgrade/rebuild
+message. Run `ctxt init . --offline` to rebuild; the synonym cache is reused.
+Search ranking and JSON output may evolve during the beta series.
+
+Existing config files are not rewritten. Replace private HTTP defaults if you
+want OpenRouter, set `watch.search_log = false`, and use `persist = "shutdown"`.
+Remove obsolete interval settings. Repeated parent/file suffixes can still
+share synonym cache entries; this key format is retained for compatibility.

CHANGELOG.md

@@ -0,0 +1,20 @@
+# Contributing
+
+Use Go 1.25 or newer. Keep changes small and include regression coverage for
+behavior changes. Run:
+
+```sh
+go test ./...
+go test -race ./...
+go vet ./...
+staticcheck ./...
+golangci-lint run
+govulncheck ./...
+```
+
+The CI workflow installs pinned analysis tools. Tests use local fake LLM
+servers and do not require API credentials. Full tests build a CLI and exercise
+MCP and watch subprocesses; `go test -short ./...` skips that lifecycle test.
+
+Do not commit generated indexes, binaries, API keys or private fixtures.
+See SECURITY.md for data handling and AGENTS.md for architecture.

CONTRIBUTING.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ken Taylor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

LICENSE

@@ -1,6 +1,6 @@
 VERSION := $(shell git describe --tags --always --dirty 2>/dev/null | sed 's/^v//' || echo "0.0.1")
 
-.PHONY: build install test
+.PHONY: build install test check dist
 
 build:
 	go build -ldflags "-X github.com/ktappdev/contexting.Version=$(VERSION)" -o bin/ctxt ./cmd/ctxt
@@ -10,3 +10,14 @@ install:
 
 test:
 	go test ./...
+
+check:
+	go test ./...
+	go test -race ./...
+	go vet ./...
+	staticcheck ./...
+	golangci-lint run
+	govulncheck ./...
+
+dist:
+	go run ./internal/dist -version v$(VERSION)