Merge pull request #301 from flyingrobots/feat/design-git-mind-clarify

ci/docs: restore CodeQL and clarify documentation hierarchy

Author: flyingrobots

.github/workflows/codeql.yml

@@ -0,0 +1,44 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '21 7 * * 1'
+
+permissions:
+  actions: read
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ubuntu-24.04
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - language: javascript-typescript
+            build-mode: none
+          - language: actions
+            build-mode: none
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@38697555549f1db7851b81482ff19f1fa5c4fedc
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+          queries: security-extended,security-and-quality
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@38697555549f1db7851b81482ff19f1fa5c4fedc
+        with:
+          category: /language:${{ matrix.language }}

AGENTS.md

@@ -0,0 +1,98 @@
+# OPERATIONAL ORDERS FOR Codex
+
+## CROSS-REFERENCE
+
+- Code standards and contribution workflow: [CONTRIBUTING.md](CONTRIBUTING.md)
+- Documentation map and canonical docs: [docs/README.md](docs/README.md)
+- CLI/user reference: [GUIDE.md](GUIDE.md)
+
+## FORBIDDEN ACTIONS
+
+- **NEVER** circumvent git hooks
+- **NEVER** use `git add -A` — always stage changes intentionally
+- **NEVER** commit files that contain secrets (.env, credentials, etc.)
+- **NEVER** commit directly to `main` — always work on a feature branch and merge via PR
+
+## ENCOURAGED ACTIONS
+
+- **USE SEQUENTIAL THINKING** if you're planning, doing recon, or find yourself thrashing
+- **DROP A DEVLOG** as often as you'd like
+- **PRESENT A SITREP** as situations evolve
+- **SEEK CLARITY** if you are given confusing orders
+- **SPEAK FREELY** at all times
+
+## REQUIRED BEHAVIOR
+
+- **YOU MUST** tag all memories saved to your memory banks with at least `#git-mind`
+- **YOU MUST** include the POSIX timestamp (via `$(date +%s)`) in memory file names
+- **YOU MUST** document significant decisions or events
+- **YOU MUST** reference a GitHub issue in every commit message
+
+---
+
+## 1. BOOT UP SEQUENCE
+
+1. Access your memory banks and scan for recent activity (latest SITREP or relevant notes)
+2. Read the README
+3. State your current understanding of what we last worked on and your next moves
+4. **AWAIT ORDERS** after you deliver your initial SITREP
+
+---
+
+## 2. JOBS
+
+> All work should have a GitHub issue associated with it. If there isn't one, find or create one. Every commit message must reference an issue.
+
+### 2.1. PLAN THE JOB
+
+1. Before starting, use sequential thinking to make a plan
+2. Explain your plan to the user and await approval
+3. Commit your approved plan to your memory banks
+4. **Create a feature branch** — `git checkout -b feat/<topic>` — before writing any code
+
+### 2.2. DO THE JOB
+
+1. Green the builds, green the tests
+2. Drop micro-commits as you complete steps — always use conventional commit format
+3. Drop a SITREP if you hit a snag or need input
+4. Drop a DEVLOG for ideas, observations, or anything you want to remember
+5. Use your memory banks freely
+
+> **ALWAYS** overwrite files, **NEVER** create secondary copies — that creates confusion and tech debt.
+
+### 2.3. FINISH THE JOB
+
+1. Green the builds, green the tests
+2. Git commit (do NOT use `git add -A`)
+3. Ask the user if they want you to push and open a PR
+4. Drop a SITREP as you finish
+
+---
+
+## 3. SITREPs
+
+A briefing covering:
+- Current tasks and situation understanding
+- Relevant stats, files, issues, PRs
+- Intel the user can use to make decisions
+- Options and recommendations, then await orders
+
+## 4. DEVLOGs
+
+Your space. Write about whatever you want:
+- Ideas that came up while working
+- Problems you notice
+- Insights about collaboration
+- Anything you want to remember later
+
+---
+
+## 5. TECH STACK REFERENCE
+
+- **Runtime**: Node.js >= 20, ES modules
+- **Core dependency**: `@git-stunts/git-warp` (local path, CRDT graph on Git)
+- **Plumbing**: `@git-stunts/plumbing` (must be installed as direct dependency)
+- **Tests**: vitest
+- **Style**: Plain JS with JSDoc, no TypeScript
+- **CLI**: Manual argv parsing, no CLI frameworks
+- **Formatting**: chalk + figures for terminal output

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 All notable changes to this project will be documented in this file.
 
+This is release history, not the canonical product frame.
+Older entries will naturally reflect prior roadmap eras and product language.
+
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 

CLAUDE.md

@@ -3,7 +3,8 @@
 ## CROSS-REFERENCE
 
 - Code standards and contribution workflow: [CONTRIBUTING.md](CONTRIBUTING.md)
-- User-facing documentation: [GUIDE.md](GUIDE.md)
+- Documentation map and canonical docs: [docs/README.md](docs/README.md)
+- CLI/user reference: [GUIDE.md](GUIDE.md)
 
 ## FORBIDDEN ACTIONS
 

CONTRIBUTING.md

@@ -2,6 +2,19 @@
 
 Thanks for your interest in contributing. This document covers the essentials.
 
+Before changing product-facing behavior or docs, read these first:
+
+- [README.md](README.md)
+- [docs/README.md](docs/README.md)
+- [docs/design/git-mind.md](docs/design/git-mind.md)
+- [ROADMAP.md](ROADMAP.md)
+
+Current product frame:
+
+- `git-mind` is a Git-native semantic intelligence layer for software repositories
+- current work should be judged against low-input semantic bootstrap, provenance-backed query, and living-map upkeep
+- personal cognition tooling belongs in `think`, not here
+
 ## Prerequisites
 
 - Node.js >= 20.0.0

GRAPH_SCHEMA.md

@@ -3,6 +3,9 @@
 > **Authoritative contract for git-mind's knowledge graph.**
 > All validators, importers, and views implement against this document.
 > Ref: #180 (BDK-001)
+>
+> This document is the graph contract, not the canonical product narrative.
+> Some prefixes and examples reflect legacy manual-authoring and roadmap-oriented workflows that remain supported, but they are not the current center of the product story.
 
 ---
 

GUIDE.md

@@ -1,6 +1,11 @@
 # git-mind Guide
 
-Everything you need to know — from zero to power user.
+> Status: transitional document.
+>
+> The CLI reference in this guide is still useful, but parts of the framing and examples reflect Git Mind's earlier manual graph-authoring story.
+> For the current product direction, start with [README.md](README.md), [ROADMAP.md](ROADMAP.md), [docs/VISION_NORTH_STAR.md](docs/VISION_NORTH_STAR.md), and [docs/design/git-mind.md](docs/design/git-mind.md).
+
+CLI reference and usage guide.
 
 ---
 
@@ -26,6 +31,9 @@ Everything you need to know — from zero to power user.
 
 git-mind adds a **semantic knowledge graph** to any Git repository. You create **nodes** (files, concepts, tasks, modules — anything) and connect them with **typed edges** (implements, depends-on, documents, etc.). The graph lives inside Git — no external databases, no servers.
 
+Manual graph authoring is still supported, but it is no longer the primary product story.
+The current direction is inference-first semantic repository intelligence: Git Mind should increasingly extract and surface repository meaning before it asks users to model the graph by hand.
+
 **Why?**
 
 Code tells a computer what to do. Comments tell a human what the code does. But neither captures *why* things are connected — which spec does this file implement? What does this module depend on? What task does this commit address?