docs: add CONTRIBUTING guide and issue/PR templates

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,29 @@
+---
+name: Bug report
+about: Something in the CLI / ingest / compile pipeline isn't working
+title: "bug: "
+labels: bug
+---
+
+## What happened
+<!-- A clear description of the bug. -->
+
+## Steps to reproduce
+1.
+2.
+3.
+
+## Expected vs actual
+- Expected:
+- Actual:
+
+## Context
+- Source kind (if relevant): blog / YouTube / repo / PDF
+- Source URL or minimal repro (if relevant):
+- Command run (e.g. `mask ingest …`, or `bun run dev …`):
+- Adapter: claude-code / agents-md
+- OS + Bun version (`bun --version`):
+- yt-dlp / git / pdftotext version (if the bug is source-specific):
+
+## Logs / output
+<!-- Paste the relevant CLI output. -->

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Developer guide (AGENTS.md)
+    url: https://github.com/TTigger/mask/blob/main/AGENTS.md
+    about: How the codebase is structured and the house rules — read before contributing.
+  - name: Docs (PRD / SPEC / PHASES)
+    url: https://github.com/TTigger/mask/tree/main/docs
+    about: Design background for the framework.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,18 @@
+---
+name: Feature request
+about: Suggest a new source, adapter, or capability
+title: "feat: "
+labels: enhancement
+---
+
+## Problem / motivation
+<!-- What can't you do today? Who is it for? -->
+
+## Proposed solution
+<!-- What would you like mask to do? Which layer does it touch — ingest (source), adapter (agent), recipe (extraction), or CLI? -->
+
+## Alternatives considered
+<!-- Optional. -->
+
+## Notes
+<!-- Keep in mind: the CLI calls no LLM; intelligence is borrowed from the user's agent. External tools must stay injectable/testable offline. -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+<!-- Keep PRs focused: one minimal, verifiable change. See CONTRIBUTING.md / AGENTS.md. -->
+
+## What & why
+<!-- What does this change, and what problem does it solve? -->
+
+## How
+<!-- Brief notes on the approach. Which layer(s): ingest / adapter / recipe / CLI / docs? -->
+
+## Checklist
+- [ ] `bun run typecheck` passes
+- [ ] `bun test` passes
+- [ ] `bun run build` passes (if touching the binary / embedded assets)
+- [ ] External tools stay injectable; new logic is unit-tested offline (no network in tests)
+- [ ] The CLI still calls no LLM; no API keys added
+- [ ] Conventional-commit title (e.g. `fix(youtube): …`)

CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing to mask
+
+Thanks for helping out! mask is small, deterministic, and agent-native — contributions that keep it that way are easy to land.
+
+> The full developer guide lives in **[AGENTS.md](AGENTS.md)** (read by Claude Code, Codex, Cursor, Gemini, …). This page is the short version; AGENTS.md is the source of truth.
+
+## Dev setup
+
+Requires [Bun](https://bun.sh).
+
+```sh
+git clone https://github.com/TTigger/mask && cd mask
+bun install
+bun run dev <command>   # run the CLI straight from the clone, e.g. `bun run dev list`
+```
+
+## Before you open a PR
+
+Run the same three checks CI runs (see `.github/workflows/ci.yml`):
+
+```sh
+bun run typecheck   # tsc --noEmit
+bun test            # the deterministic-core suite
+bun run build       # single executable — needed for anything touching the binary / embedded assets
+```
+
+Keep the tree green between commits.
+
+## House rules (the short list)
+
+- **The CLI calls no LLM.** Everything under `src/` is deterministic; the "intelligence" is borrowed from the user's agent following a recipe. The only sanctioned exception is `mask scale` (shells out to the user's *own* headless agent CLI). Never add a model API or key.
+- **Framework ≠ library.** This repo is the tool; a user's masks live in `~/.mask/`. Don't store masks here.
+- **External tools are injectable.** New ingest modules take a fetcher/provider/extractor that defaults to the real tool (git / yt-dlp / pdftotext) with a fake in tests — the suite must run offline. Prefer extracting pure helpers and unit-testing those (see `parseVtt`, `pickSubtitleLang`).
+- **Evidence-bound output.** Distilled claims trace to a source sample `[src:id]`; thin coverage is declared, not hidden.
+- **Add an agent** via an adapter, **add a source** via an ingest module — the recipe stays put. The three layers are independent.
+
+## Commits & PRs
+
+- One minimal, verifiable change per commit.
+- Conventional-commit messages, e.g. `fix(youtube): …`, `feat(ingest): …`, `docs: …`.
+- Keep the PR focused; fill in the PR template checklist.
+
+## Reporting bugs / proposing features
+
+Open an issue using the templates. For ingest bugs, include the source kind (blog / YouTube / repo / PDF) and, if relevant, the URL or a minimal repro.

README.md

@@ -116,6 +116,10 @@ The CLI is deterministic and calls **no LLM** — your agent does the intelligen
 - `MASK_AGENTS_MD` — the AGENTS.md install target (default `./AGENTS.md`; `init --out <dir>` sets this).
 - `MASK_FRAMEWORK` — set this when running the **standalone compiled binary** so the agent can still find the on-disk recipe/templates; point it at the cloned repo. (Unnecessary with `bun run`/`bunx`, which resolve them automatically.)
 
+## Contributing
+
+Issues and PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) (and [AGENTS.md](AGENTS.md) for the full developer guide).
+
 ## License
 
 MIT

README.zh-TW.md

@@ -108,6 +108,10 @@ CLI 是決定性的、**不呼叫任何 LLM** —— 智慧工作由你的 agent
 - `MASK_AGENTS_MD` —— AGENTS.md 安裝目標（預設 `./AGENTS.md`；`init --out <dir>` 會設定它）。
 - `MASK_FRAMEWORK` —— 跑**獨立編譯二進位**時設定，讓 agent 仍找得到磁碟上的 recipe/templates；指向 clone 的 repo。（用 `bun run`/launcher 時不需要，會自動解析。）
 
+## 參與貢獻
+
+歡迎開 issue 與 PR —— 請看 [CONTRIBUTING.md](CONTRIBUTING.md)（完整開發指南在 [AGENTS.md](AGENTS.md)）。
+
 ## License
 
 MIT