ci: enforce PR-based workflow with branch protection, DOX tracking, Dependabot

.github/AGENTS.md

@@ -0,0 +1,44 @@
+# .github/
+
+## Purpose
+
+GitHub repository configuration: CI/CD workflows, release automation, and issue/PR templates. Defines what runs on `main` pushes, PRs, and version tags.
+
+## Ownership
+
+### Workflows (`workflows/`)
+- `ci.yml` — CI on push/PR to `main`. Steps: `bun install` → `bun run typecheck` → `bun run build` → `bun run test` → `bun audit` (non-blocking: `continue-on-error: true`, dev-only findings don't gate `main`). Permissions: `contents: read`
+- `sonarcloud.yml` — Runs `bun run test:coverage` and uploads the LCOV report to SonarCloud on push/PR to `main`. Coverage exclusions in `sonar-project.properties` (repo root)
+- `release.yml` — Triggered by `v*` tag pushes. Runs typecheck, build, test; checks if the version is already on npm and if a GitHub release exists; publishes to npm (Node 24, `NPM_TOKEN` secret, `https://registry.npmjs.org`) and creates a GitHub Release with body extracted from `docs/CHANGELOG.md` plus auto-generated PR notes. Idempotent — re-runs won't duplicate publishes/releases
+- `opencode.yml` — OpenCode-related workflow
+
+### Templates and community files (repo root of `.github/`)
+- `pull_request_template.md` — PR checklist (typecheck, test, build, style, JSDoc, README/CHANGELOG)
+- `ISSUE_TEMPLATE/bug_report.md`, `ISSUE_TEMPLATE/feature_request.md` — Issue templates
+- `CONTRIBUTING.md` — Contributor guide including Release Process, Contributor Credits, and Version Numbering sections; the canonical contributor reference is `docs/DEVELOPMENT.md` + `docs/TESTING.md`
+- `SECURITY.md` — Private vulnerability reporting policy (GitHub security advisory or direct contact to @ZeR020). Supported versions and disclosure timeline
+- `CODE_OF_CONDUCT.md` — Contributor Covenant
+- `banner.png`, `screenshot-*.png` — README assets
+
+## Local Contracts
+
+- CI gates on `main`: typecheck, build, test must pass. `bun audit` runs but is non-blocking (dev-only vulnerabilities don't gate CI). The same checks run on PRs
+- Release is tag-driven (`v*`) only; never publish to npm outside the release workflow. `NPM_TOKEN` is the required repository secret
+- The release workflow is idempotent (checks `npm view` and `gh release view` before acting) — preserve those guards
+- `permissions` blocks are scoped (`contents: read` for CI, `contents: write` for release) — do not broaden them
+- SonarCloud coverage exclusions live in `sonar-project.properties`; keep them aligned with `vitest.config.ts` coverage excludes
+
+## Work Guidance
+
+- New CI check → add to `ci.yml` and to the local verification list in the root AGENTS.md and `docs/DEVELOPMENT.md`
+- Release process: bump `package.json`, update `docs/CHANGELOG.md`, commit, tag `v*`, push `main --tags`. See `docs/DEVELOPMENT.md`
+- Security issues are reported privately per `SECURITY.md` — never via a public issue or workflow change
+
+## Verification
+
+- CI runs on every push/PR to `main` and must be green
+- Release workflow is verified end-to-end only on an actual `v*` tag; dry-run by checking the `release_state` step logic locally
+
+## Child DOX Index
+
+No child AGENTS.md files. This is a leaf boundary.

.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+    commit-message:
+      prefix: "chore"
+      include: scope

.github/pull_request_template.md

@@ -1,8 +1,11 @@
 ## Description
-<!-- Briefly describe what this PR does -->
+
+<!-- Briefly describe what this PR does and why -->
 
 ## Type of Change
+
 <!-- Mark relevant options with an [x] -->
+
 - [ ] Bug fix
 - [ ] New feature
 - [ ] Breaking change
@@ -11,17 +14,32 @@
 - [ ] Refactoring
 
 ## Checklist
+
 <!-- Mark completed items with an [x] -->
+
 - [ ] I have run `bun run typecheck` and it passes
-- [ ] I have run `npm test` or `bun run test` and all tests pass
+- [ ] I have run `bun run test` and all tests pass
 - [ ] I have run `bun run build` and it succeeds
+- [ ] I have run `bun run format:check` and it passes
 - [ ] My code follows the project's style guidelines
 - [ ] I have added JSDoc comments for new public functions
-- [ ] I have updated the README/CHANGELOG if needed
+- [ ] I have updated `docs/CHANGELOG.md` if user-facing
+- [ ] I have updated `docs/` docs if behavior changed
 
 ## Testing
+
 <!-- Describe how you tested your changes -->
 
 ## Related Issues
-<!-- Link to any related issues -->
+
+<!-- Link to any related issues. Use "Fixes #N" to auto-close on merge -->
+
 Fixes #(issue number)
+
+## Changelog Entry
+
+<!-- If user-facing, add a one-line summary for the changelog (Added/Fixed/Removed/Changed) -->
+
+## Contributor Credit
+
+<!-- If this PR fixes an issue reported by someone else, credit them: "Thanks to @username for reporting #N" -->

.gitignore

@@ -49,8 +49,9 @@ logs/
 *~
 
 # ─── Agent & work files (never commit) ─────────────────────────
-# DOX hierarchy, agent configs, personal tooling
+# DOX hierarchy — track AGENTS.md (binding work contracts), ignore personal tooling
 AGENTS.md
+!AGENTS.md
 .claude/
 .cursor/
 .cursorrules

.husky/AGENTS.md

@@ -0,0 +1,33 @@
+# .husky/
+
+## Purpose
+
+Git hooks managed by Husky. Enforces security checks, type safety, formatting, and DeepSource-equivalent linting before commits and pushes reach CI.
+
+## Ownership
+
+- `pre-commit` — Runs on `git commit`. (1) Blocks staging of sensitive file patterns (`.env*`, `.pem`, `.key`, secrets, credentials, archives, editor cruft, `.opencode/*`, `.planning/*`, etc.) and sensitive directories. (2) Scans staged text files for common secret/API key patterns (`sk-...`, `ghp_...`, `AKIA...`, `glpat-...`, `npm_...`, etc.) and warns interactively. (3) Flags tracked files matching `.gitignore`. (4) Runs `bun run typecheck && bunx lint-staged` (Prettier auto-format on staged files)
+- `pre-push` — Runs on `git push`. Invokes `bash scripts/lint-deepsource.sh` to catch DeepSource JS analyzer issues (async-without-await, `var`, loose equality, `console.*` outside logger, empty catch, non-null `!` / `any` without `skipcq`) before they fail CI
+
+## Local Contracts
+
+- Both hooks are load-bearing gates; the rules they encode mirror the root AGENTS.md `Local Contracts` and `scripts/lint-deepsource.sh`. Keep all three in sync when a rule changes
+- `pre-commit` blocks (not just warns) on sensitive file patterns and directories — do not weaken this. Bypass only via `git commit --no-verify` in genuine test/mock cases
+- `lint-staged` runs Prettier on staged `*.{ts,tsx,js,jsx,css,html,json,md}` (config in `package.json`)
+- Husky is installed via `npm run prepare` → `husky` (wired in `package.json` `scripts.prepare`)
+
+## Work Guidance
+
+- Adding a sensitive pattern → add to the `pre-commit` `case` block and note it in the root AGENTS.md
+- Adding a DeepSource rule → add to `scripts/lint-deepsource.sh` (which `pre-push` runs) and the root `Local Contracts`
+- Hooks are shell scripts (`#!/bin/sh`) — keep them POSIX-compatible
+
+## Verification
+
+- A blocked file pattern aborts the commit with a non-zero exit
+- `pre-commit` runs `bun run typecheck` (strict) — any type error aborts the commit
+- `pre-push` runs the DeepSource lint — any finding aborts the push
+
+## Child DOX Index
+
+No child AGENTS.md files. This is a leaf boundary.

AGENTS.md

@@ -0,0 +1,145 @@
+# DOX framework
+
+- DOX is highly performant AGENTS.md hierarchy installed here
+- Agent must follow DOX instructions across any edits
+
+## Core Contract
+
+- AGENTS.md files are binding work contracts for their subtrees
+- Work products, source materials, instructions, records, assets, and durable docs must stay understandable from the nearest applicable AGENTS.md plus every parent AGENTS.md above it
+
+## Read Before Editing
+
+1. Read the root AGENTS.md
+2. Identify every file or folder you expect to touch
+3. Walk from the repository root to each target path
+4. Read every AGENTS.md found along each route
+5. If a parent AGENTS.md lists a child AGENTS.md whose scope contains the path, read that child and continue from there
+6. Use the nearest AGENTS.md as the local contract and parent docs for repo-wide rules
+7. If docs conflict, the closer doc controls local work details, but no child doc may weaken DOX
+
+Do not rely on memory. Re-read the applicable DOX chain in the current session before editing.
+
+## Update After Editing
+
+Every meaningful change requires a DOX pass before the task is done.
+
+Update the closest owning AGENTS.md when a change affects:
+
+- purpose, scope, ownership, or responsibilities
+- durable structure, contracts, workflows, or operating rules
+- required inputs, outputs, permissions, constraints, side effects, or artifacts
+- user preferences about behavior, communication, process, organization, or quality
+- AGENTS.md creation, deletion, move, rename, or index contents
+
+Update parent docs when parent-level structure, ownership, workflow, or child index changes. Update child docs when parent changes alter local rules. Remove stale or contradictory text immediately. Small edits that do not change behavior or contracts may leave docs unchanged, but the DOX pass still must happen.
+
+## Hierarchy
+
+- Root AGENTS.md is the DOX rail: project-wide instructions, global preferences, durable workflow rules, and the top-level Child DOX Index
+- Child AGENTS.md files own domain-specific instructions and their own Child DOX Index
+- Each parent explains what its direct children cover and what stays owned by the parent
+- The closer a doc is to the work, the more specific and practical it must be
+
+## Child Doc Shape
+
+- Create a child AGENTS.md when a folder becomes a durable boundary with its own purpose, rules, responsibilities, workflow, materials, or quality standards
+- Work Guidance must reflect the current standards of the project or user instructions; if there are no specific standards or instructions yet, leave it empty
+- Verification must reflect an existing check; if no verification framework exists yet, leave it empty and update it when one exists
+
+Default section order:
+
+- Purpose
+- Ownership
+- Local Contracts
+- Work Guidance
+- Verification
+- Child DOX Index
+
+## Style
+
+- Keep docs concise, current, and operational
+- Document stable contracts, not diary entries
+- Put broad rules in parent docs and concrete details in child docs
+- Prefer direct bullets with explicit names
+- Do not duplicate rules across many files unless each scope needs a local version
+- Delete stale notes instead of explaining history
+- Trim obvious statements, repeated rules, misplaced detail, and warnings for risks that no longer exist
+
+## Closeout
+
+1. Re-check changed paths against the DOX chain
+2. Update nearest owning docs and any affected parents or children
+3. Refresh every affected Child DOX Index
+4. Remove stale or contradictory text
+5. Run existing verification when relevant
+6. Report any docs intentionally left unchanged and why
+
+## User Preferences
+
+When the user requests a durable behavior change, record it here or in the relevant child AGENTS.md
+
+---
+
+# opencode-mem0
+
+## Purpose
+
+OpenCode plugin that gives coding agents persistent, private long-term memory via a local vector database (SQLite + usearch). No cloud services required — all data stays on the user's machine. The plugin intercepts OpenCode chat/session events, stores technical knowledge as vector-embedded memories, and injects relevant context back into agent conversations.
+
+Cognitive enhancement fork of `tickernelz/opencode-mem`, published to npm as `opencode-mem0`. Maintained by ZeR020 under the MIT license.
+
+## Ownership
+
+- Repository: `github.com/ZeR020/opencode-mem0`, default branch `main`
+- Package: `opencode-mem0` on npm; published artifacts are `dist/`, `package.json`, `README.md`, `LICENSE`, `docs/CHANGELOG.md`
+- Runtime: Bun >= 1.0.0 (primary, Linux/macOS, native `bun:sqlite`) or Node.js >= 20.0.0 (fallback, any platform, `better-sqlite3`)
+- Language: strict TypeScript, ESM (`"type": "module"`)
+- Versioning/release: Conventional Commits, automated via `.github/workflows/release.yml` on `v*` tags
+
+## Local Contracts
+
+- TypeScript strict mode is mandatory: `strict`, `noUncheckedIndexedAccess`, `noImplicitOverride`, `noFallthroughCasesInSwitch`, `verbatimModuleSyntax`. Prefer explicit types over `any`; use `unknown` then narrow when the type is truly unknown
+- JSDoc required on all public functions, classes, and exported constants (`@param`, `@returns`, behavior + side effects)
+- Prettier is the formatter: semicolons, double quotes, 2-space indent, 100 char width, ES5 trailing commas, LF. Run `bun run format` before committing
+- Conventional Commits only: `type(scope): description`, present tense. Valid types: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `ci`
+- No `console.*` outside the logger module; no `var`; no loose `==`/`!=` outside null checks; no empty catch blocks; no non-null `!` or explicit `any` without `skipcq` annotation (DeepSource rules enforced by `scripts/lint-deepsource.sh`)
+- New AI providers and embedding backends integrate through the existing factory/abstraction seams — never bypass `AIProviderFactory` or the `VectorBackend` interface
+- All data stays local. Never add cloud telemetry, remote reporting, or outbound network calls beyond the user-configured embedding/AI endpoints
+- Privacy boundaries are load-bearing: secrets and PII are stripped by `privacy.ts` before any LLM call; preserve that invariant in any capture path
+- **No direct commits to `main`** — branch protection is enforced for all users including admins. Every change goes through a PR: branch → commit → push → PR → CI → merge. Branch naming: `fix/<desc>`, `feat/<desc>`, `refactor/<desc>`, `chore/<desc>`, `docs/<desc>`
+- **PR titles use Conventional Commits** — `fix(scope): description`, `feat(scope): description`, etc. Link issues with `Fixes #N` in the PR body so GitHub auto-closes them on merge and credits the reporter in release notes
+- **Squash merge only** — `required_linear_history` is enabled. PRs are squash-merged to keep `main` history clean with one commit per PR
+- **Release process**: bump version in `package.json` → write `docs/CHANGELOG.md` entry (Added/Fixed/Removed/Changed/Closed/Contributors) → commit → tag `vX.Y.Z` → push tag. The release workflow auto-publishes to npm and creates the GitHub release from the changelog
+- **Contributor credits**: community contributors who report issues or submit PRs are credited by GitHub username in the `docs/CHANGELOG.md` Contributors section for the release that ships their contribution
+
+## Work Guidance
+
+- Reuse existing patterns before introducing new ones. A second convention beside an existing one is prohibited
+- Run `lsp references` before modifying exported symbols — missed callsites are bugs
+- New services go in `src/services/<name>.ts`, get JSDoc, integrate through `src/services/client.ts` when part of the primary API surface, and ship with `tests/<name>.test.ts`
+- Keep PRs focused; separate unrelated changes. Verify locally before opening: `bun run typecheck && bun run test && bun run build && bun run format:check && bash scripts/lint-deepsource.sh`
+- When changing user-facing behavior, update the matching doc in `docs/` (`CONFIGURATION.md`, `GETTING-STARTED.md`, `DEVELOPMENT.md`, `ARCHITECTURE.md`) and any JSON schema/example configs
+
+## Verification
+
+- `bun run typecheck` — strict `tsc --noEmit`, zero errors
+- `bun run test` — full Vitest suite (`tests/**/*.test.ts`, 430+ tests, node env, `tests/setup-home.ts` isolates HOME)
+- `bun run build` — `tsc` to `dist/` + copy `src/web/` to `dist/web/` via `scripts/build.mjs`
+- `bun audit` — dependency vulnerability scan (non-blocking in CI: dev-only findings don't gate `main`)
+- `bun run format:check` — Prettier check
+- `bash scripts/lint-deepsource.sh` — local DeepSource-equivalent lint (runs on pre-push)
+- CI (`.github/workflows/ci.yml`): typecheck → build → test → audit (non-blocking), all gates pass on `main`
+
+## Child DOX Index
+
+| Path                | Scope                                                                    |
+| ------------------- | ------------------------------------------------------------------------ |
+| `src/AGENTS.md`     | Source root: plugin entry point, config layer, shared types, plugin shim |
+| `tests/AGENTS.md`   | Vitest test suite conventions and mocking patterns                       |
+| `scripts/AGENTS.md` | Build, lint, and migration scripts                                       |
+| `docs/AGENTS.md`    | Project documentation set                                                |
+| `.github/AGENTS.md` | CI workflows, issue/PR templates, release automation                     |
+| `.husky/AGENTS.md`  | Git hooks (pre-commit, pre-push)                                         |
+
+Source service subsystems are indexed under `src/AGENTS.md` → `src/services/AGENTS.md`, which owns the service-layer children (`sqlite/`, `vector-backends/`, `ai/`, `user-profile/`). The `src/web/` UI assets are indexed directly under `src/AGENTS.md` (they sit under `src/`, not `src/services/`). The `src/services/handlers/` directory has no separate AGENTS.md — see `src/services/AGENTS.md`.

docs/AGENTS.md

@@ -0,0 +1,39 @@
+# docs/
+
+## Purpose
+
+Project documentation set. User-facing and contributor-facing docs covering setup, configuration, architecture, development, testing, and release history. `docs/CHANGELOG.md` is shipped in the published package; the rest are repo-only.
+
+## Ownership
+
+- `README.md` (repo root, not here) — Project overview, install, usage, config reference. The public face of the package
+- `GETTING-STARTED.md` — First-run guide: prerequisites, install steps, minimal config, verification, next steps
+- `CONFIGURATION.md` — Full configuration reference: file locations, deep-merge order, every setting with default and description. The source of truth for config fields
+- `ARCHITECTURE.md` — System overview, data flow (memory injection, storage, auto-capture, lifecycle, compaction recovery), key abstractions, directory structure, storage layout, vector search pipeline, configuration layer
+- `DEVELOPMENT.md` — Contributor guide: setup, build commands, code style (Prettier, strict TS, DeepSource lint, JSDoc), branch conventions, PR process, project structure, release process
+- `TESTING.md` — Test framework, running tests, writing new tests, mocking patterns, HOME isolation, coverage, CI integration
+- `CHANGELOG.md` — Keep a Changelog format, Semantic Versioning. **Shipped in the published package** (`package.json` `files`). Updated per release
+
+## Local Contracts
+
+- These docs carry a `<!-- generated-by: gsd-doc-writer -->` header marking their origin; treat them as maintained prose, not auto-generated throwaway
+- `CONFIGURATION.md` is the source of truth for config fields. Adding/removing/renaming a field in `src/config.ts` requires a matching update here and in the Zod schema
+- `ARCHITECTURE.md` describes the system data flow and key abstractions; structural changes (new service, changed flow, new abstraction) require an update here
+- `CHANGELOG.md` is the only doc shipped to npm — keep entries user-facing and grouped under Keep a Changelog categories (`Added`, `Changed`, `Fixed`, `Security & Reliability`, etc.)
+- `DEVELOPMENT.md` and `TESTING.md` encode the contributor workflow that the root and `tests/` AGENTS.md files also reference — keep them consistent
+
+## Work Guidance
+
+- User-facing behavior change → update the relevant doc here plus `README.md`
+- Config field change → update `CONFIGURATION.md` and the Zod schema together
+- Release → bump `package.json` version, add a `CHANGELOG.md` entry, tag `v*` (see `DEVELOPMENT.md` release process)
+- Prefer editing existing docs over creating new ones
+
+## Verification
+
+- No automated doc lint exists. Manual review on PR; the PR template asks for doc updates when behavior changes
+- `CHANGELOG.md` accuracy is verified at release time against the git log
+
+## Child DOX Index
+
+No child AGENTS.md files. This is a leaf boundary.