Skip to content

Self-hosted MCP server + dashboard giving Claude Code, Cursor & Hermes agents shared long-term memory over a git-backed markdown vault. Agent-native, Obsidian-compatible second brain — markdown RAG, no vector DB.

chore: CI (lint + build) + PR template + CONTRIBUTING

Ronalds Palacisf808a7e6be53
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..225e4b3
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,15 @@
+## What & why
+
+<!-- What does this change, and why? Link any related issue. -->
+
+## How I verified it
+
+<!-- Not just "tests pass" — how did you exercise the change in the running app? -->
+
+## Checklist
+
+- [ ] `bun run lint` passes
+- [ ] `bun run build` passes (type-checks + compiles)
+- [ ] Verified the change in the running app (`bun dev`), not only in theory
+- [ ] Updated docs (README / DEPLOY / .env.example) if behavior or config changed
+- [ ] No secrets, tokens, or real vault content committed
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..2e332ee
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,36 @@
+name: CI
+
+on:
+ push:
+ branches: [main]
+ pull_request:
+
+# Cancel superseded runs on the same ref.
+concurrency:
+ group: ci-${{ github.ref }}
+ cancel-in-progress: true
+
+env:
+ NEXT_TELEMETRY_DISABLED: "1"
+
+jobs:
+ build:
+ name: lint + build
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Setup bun
+ uses: oven-sh/setup-bun@v2
+ with:
+ bun-version: latest
+
+ - name: Install dependencies
+ run: bun install --frozen-lockfile
+
+ - name: Lint
+ run: bun run lint
+
+ # `next build` type-checks (tsc) and compiles every route — the real gate.
+ - name: Build
+ run: bun run build
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..e3cbbad
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,42 @@
+# Contributing to Engram
+
+Thanks for helping improve Engram. It's an agent-first, markdown-native second brain — a
+dashboard for humans and an MCP server for agents over a git-backed vault. Keep changes small,
+verified, and in the grain of the existing code.
+
+## Getting started
+
+```bash
+bun install
+bun dev # http://localhost:3000, runs against ./sample-vault
+bun run build # production build (also type-checks)
+bun run lint # eslint
+```
+
+Point it at your own vault: `VAULT_DIR=/path/to/vault bun dev`.
+
+## Stack & conventions
+
+- **Next.js 16 (App Router, Turbopack), React 19, TypeScript (strict), Tailwind v4, shadcn/base-ui, bun.**
+- Tailwind v4 has **no config file** — the theme lives in `app/globals.css` (`@theme inline`).
+- base-ui primitives have **no `asChild`**.
+- Next 16 route handlers: `params` is a **Promise** (`const { path } = await params`).
+- **Files are the source of truth** — there is no database. The vault is markdown; app state
+ (tokens, workspaces, settings) lives under `CORTEX_DATA_DIR`/`ENGRAM_DATA_DIR`, never inside a vault.
+- The MCP layer exposes **only** vault tools — never repo/workspace/GitHub internals.
+- Match the surrounding code's naming, comment density, and idiom.
+
+## Before you open a PR
+
+1. `bun run lint` and `bun run build` both pass (CI runs these on every PR).
+2. **Verify in the running app**, not just in theory — drive the actual flow you changed.
+3. Update docs (`README.md`, `DEPLOY.md`, `.env.example`) if you changed behavior or config.
+4. Never commit secrets, tokens, or real vault content. `.cortex-data` / `.engram-data` are gitignored.
+
+## Scope
+
+Bug fixes and focused improvements are welcome as PRs directly. For larger features or anything
+that changes the data model, the MCP tool surface, or auth, please **open an issue first** so we
+can align on the approach before you build.
+
+MIT licensed — by contributing you agree your work is released under the same license.