@fentech/gitcontext 0.3.3 → 0.5.0

package/README.md

@@ -0,0 +1,392 @@
+# @fentech/gitcontext
+
+[![npm version](https://img.shields.io/npm/v/@fentech/gitcontext.svg)](https://www.npmjs.com/package/@fentech/gitcontext)
+
+AI-assisted knowledge capture for developer teams — turns git context (branches, diffs, PRs) into searchable docs: learnings, bugs, conventions, and blockers. Docs live in your repo (`.gitcontext/docs/*.md`) and sync to the [GitContext dashboard](https://app.gitcontext.app).
+
+---
+
+## Installation
+
+```sh
+npm install -g @fentech/gitcontext
+# or
+bun add -g @fentech/gitcontext
+```
+
+---
+
+## Quick Start
+
+```sh
+# 1. Log in (opens browser for GitHub OAuth)
+gitcontext auth login
+
+# 2. Set up your repo (AI platform, doc profile, GitHub App)
+gitcontext init
+
+# 3. Capture your first doc
+gitcontext capture "learned that Postgres advisory locks are perfect for distributed job deduplication"
+```
+
+---
+
+## Authentication
+
+Login opens a browser for GitHub OAuth and stores a token in `~/.gitcontext/profiles.json`.
+
+```sh
+gitcontext auth login           # log in (default "prod" profile)
+gitcontext auth login --profile staging --api-url https://staging.myapp.com
+gitcontext auth status          # show current user, org, plan, usage
+gitcontext auth list            # list all profiles
+gitcontext auth use staging     # switch active profile
+```
+
+**Override profile for a single command:**
+
+```sh
+gitcontext --profile staging analyze
+```
+
+**Profiles file** (`~/.gitcontext/profiles.json`):
+
+```json
+{
+  "active": "prod",
+  "profiles": {
+    "prod": {
+      "apiUrl": "https://app.gitcontext.app",
+      "userToken": "gct_..."
+    }
+  }
+}
+```
+
+---
+
+## Commands
+
+### Capture & Edit
+
+#### `capture [prompt]`
+
+AI-generate a doc from a natural-language prompt. Presents an accept / revise / eject loop before writing anything.
+
+```sh
+gitcontext capture "just fixed a race condition in the job queue"
+gitcontext capture                           # prompts you interactively
+gitcontext capture "..." --type bug          # force a specific doc type
+gitcontext capture "..." --no-commit         # write file but skip git commit
+gitcontext capture "..." --json              # output result as JSON
+```
+
+Include code context inline with `@` mentions:
+
+```
+gitcontext capture "learned that @src/queue/worker.ts uses a mutex to prevent double-processing"
+```
+
+GitContext resolves `@path/to/file` to the file contents and includes them as context for the AI.
+
+---
+
+#### `analyze`
+
+Analyze the current branch diff against a base branch and suggest docs to capture. Shows a checklist — select which ones to save, then commits them in one batch.
+
+```sh
+gitcontext analyze                  # compares against main
+gitcontext analyze --base develop   # compare against a different branch
+gitcontext analyze --no-commit      # write files, skip commit
+gitcontext analyze --json
+```
+
+---
+
+#### `revise [--doc <id>]`
+
+AI-assisted revision of an existing doc. Fuzzy-searches your docs if `--doc` is omitted.
+
+```sh
+gitcontext revise                              # interactive doc picker
+gitcontext revise --doc abc123                 # specify doc ID
+gitcontext revise --doc abc123 --prompt "add more detail about the root cause"
+gitcontext revise --doc abc123 --no-local      # update cloud only, skip local file
+gitcontext revise --json
+```
+
+---
+
+### Sync
+
+#### `push`
+
+Upload all local `.gitcontext/docs/*.md` files to the API. Safe to run repeatedly — existing docs are updated, unchanged ones are skipped.
+
+```sh
+gitcontext push
+gitcontext push --json
+```
+
+---
+
+### Query
+
+#### `docs`
+
+```sh
+gitcontext docs list                          # docs on current branch
+gitcontext docs list --type bug               # filter by type
+gitcontext docs list --since 7d --limit 20   # last 7 days, max 20
+gitcontext docs list --branch feature/auth
+gitcontext docs list --json
+
+gitcontext docs get <id>                      # full doc by ID
+gitcontext docs get <id> --json
+
+gitcontext docs latest                        # most recent doc on current branch
+gitcontext docs latest --branch main
+
+gitcontext docs search "race condition"       # full-text search
+gitcontext docs search "queue" --type bug --limit 10
+```
+
+---
+
+### Branch Health
+
+#### `status`
+
+Summary of the current branch: doc count by type, open blockers, last capture time, and a link to the dashboard.
+
+```sh
+gitcontext status
+```
+
+#### `blockers`
+
+```sh
+gitcontext blockers                           # open blockers on current branch
+gitcontext blockers --all                     # across all branches
+gitcontext blockers --status in_progress
+gitcontext blockers --json
+
+gitcontext blockers resolve <id>              # mark resolved (prompts for notes)
+```
+
+---
+
+### Setup
+
+#### `init`
+
+Interactive wizard that walks through:
+
+1. Authentication (opens browser if not logged in)
+2. AI platform selection (Claude Code, Cursor, Windsurf, VS Code + Copilot, Gemini)
+3. Doc profile selection (Markdown, MDX, Storybook, Docusaurus, Mintlify, Custom)
+4. GitHub App installation
+5. Writing integration files to global or repo locations
+6. Creating `.gitcontext/config.json`
+7. Optional: backfill existing markdown files
+
+```sh
+gitcontext init
+```
+
+#### `update`
+
+Re-sync integration templates (Claude Code, Cursor, etc.) from the installed package version. Run this after upgrading `@fentech/gitcontext` to pick up new agent prompts and slash commands.
+
+```sh
+gitcontext update
+```
+
+---
+
+### Knowledge Seeding
+
+#### `backfill`
+
+Adopt existing markdown files or generate docs from PR history.
+
+```sh
+# Adopt existing .md/.mdx files from the repo into .gitcontext/docs/
+gitcontext backfill --local
+
+# Generate draft docs from merged PRs (shows token cost estimate before running)
+gitcontext backfill --from-prs
+gitcontext backfill --from-prs --months 3 --max-prs 30
+```
+
+---
+
+### Discovery
+
+#### `teach`
+
+Pull a random surprising insight from the team's doc base via AI — useful for knowledge sharing and onboarding.
+
+```sh
+gitcontext teach
+gitcontext teach --type learning
+gitcontext teach --repo owner/repo --branch main
+```
+
+---
+
+### Reference
+
+#### `changelog`
+
+Display CLI release notes.
+
+```sh
+gitcontext changelog
+gitcontext changelog --limit 5
+gitcontext changelog --json
+```
+
+---
+
+## MCP Server
+
+GitContext ships an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that lets Claude Code, Cursor, and other AI tools call GitContext directly from your editor.
+
+```sh
+gitcontext mcp serve    # start stdio MCP server
+```
+
+`gitcontext init` writes the MCP config automatically for your chosen platform. To configure it manually:
+
+**Claude Code** (`~/.claude/mcp.json` or `.claude/mcp.json` in the repo):
+
+```json
+{
+  "mcpServers": {
+    "gitcontext": {
+      "command": "gitcontext",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+**Cursor / Windsurf** (`.cursor/mcp.json` / `.windsurf/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "gitcontext": {
+      "command": "gitcontext",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+### MCP Tools
+
+| Tool | Description |
+|---|---|
+| `get_git_context` | Branch, commit hash, repo name, working directory |
+| `get_git_diff` | Diff between current branch and base |
+| `get_status` | Doc count, open blockers, last capture time |
+| `process_doc` | AI-generate a structured doc (stateless) |
+| `write_doc` | Write doc to `.gitcontext/docs/` and optionally commit |
+| `ingest_doc` | Push a doc to the cloud API |
+| `revise_doc` | Fetch a doc and generate a revision (stateless) |
+| `list_docs` | List docs with type/branch/date filters |
+| `list_open_blockers` | Open blockers (optionally filtered by branch) |
+| `resolve_blocker` | Mark a blocker resolved with notes |
+
+### MCP Prompts
+
+Pre-built guided workflows available in Claude Code's prompt picker:
+
+| Prompt | Description |
+|---|---|
+| `capture_learning` | Capture a new insight or technique |
+| `capture_bug` | Document a bug, root cause, and fix |
+| `capture_blocker` | Record something blocking progress |
+| `capture_convention` | Encode a code structure or naming decision |
+| `wrap_conversation` | Summarize an AI-assisted conversation |
+| `doc_from_branch` | Analyze a branch diff and generate 3–10 docs |
+| `analyze_pr` | One-shot PR analysis and doc suggestion |
+| `revise_doc` | Interactive revision of an existing doc |
+
+---
+
+## Doc Types
+
+| Type | When to use |
+|---|---|
+| `learning` | New insight, technique, or understanding |
+| `bug` | Bug found, diagnosed, and fixed (include root cause) |
+| `convention` | Decision about how code should be structured or named |
+| `blocker` | Something blocking progress (open or resolved) |
+| `conversation` | Summary of a significant AI-assisted conversation |
+
+---
+
+## Storage Modes
+
+Each doc type can be stored in the repo, the cloud, or both:
+
+| Mode | Behavior |
+|---|---|
+| `repo` | Written to `.gitcontext/docs/*.md` and committed to git |
+| `cloud` | Sent to the API only — not committed to the repo |
+
+Configure per doc type in `.gitcontext/config.json` under `docStorageModes`. `gitcontext init` sets this up interactively.
+
+---
+
+## Doc Profiles
+
+Render targets for generated docs (chosen during `gitcontext init`):
+
+| Profile | Output format |
+|---|---|
+| `markdown` | Standard `.md` (default) |
+| `mdx` | MDX with JSX frontmatter |
+| `storybook-mdx` | Storybook-compatible MDX |
+| `docusaurus` | Docusaurus-compatible MDX with sidebar metadata |
+| `mintlify` | Mintlify-compatible MDX |
+| `custom` | Custom template |
+
+---
+
+## Repo Config
+
+`gitcontext init` writes `.gitcontext/config.json` to the repo root. Example:
+
+```json
+{
+  "repoName": "owner/repo",
+  "platforms": ["claude-code", "cursor"],
+  "storageMode": "repo",
+  "docStorageModes": {
+    "learning": "repo",
+    "bug": "repo",
+    "blocker": "cloud",
+    "convention": "repo",
+    "conversation": "cloud"
+  },
+  "docProfiles": {
+    "learning": "markdown",
+    "bug": "markdown",
+    "blocker": "markdown",
+    "convention": "markdown",
+    "conversation": "markdown"
+  }
+}
+```
+
+---
+
+## Links
+
+- **Dashboard:** [app.gitcontext.app](https://app.gitcontext.app)
+- **npm:** [npmjs.com/package/@fentech/gitcontext](https://www.npmjs.com/package/@fentech/gitcontext)