brianmeyer · brianmeyer · May 17, 2026 · May 17, 2026
diff --git a/.github/DISCUSSION_TEMPLATE/alpha-feedback.yml b/.github/DISCUSSION_TEMPLATE/alpha-feedback.yml
@@ -0,0 +1,46 @@
+title: "[Alpha]: "
+labels: ["alpha", "feedback"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for testing RecallForge early. Please avoid sharing private indexed content. Summaries and redacted snippets are enough.
+  - type: input
+    id: tester_profile
+    attributes:
+      label: Tester profile
+      description: Machine/backend/MCP client, for example "M3 Pro, MLX, Claude Desktop".
+    validations:
+      required: true
+  - type: textarea
+    id: workflow
+    attributes:
+      label: Workflow tested
+      description: What did you ingest and what did you ask RecallForge to recall?
+    validations:
+      required: true
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      options:
+        - label: Installed RecallForge and captured `recallforge --version`.
+        - label: Started the MCP server in a real client.
+        - label: Ingested at least one text item and one media/document item.
+        - label: Re-ran an ingest or update and checked that stale memories did not show up.
+  - type: textarea
+    id: quality
+    attributes:
+      label: Retrieval quality notes
+      description: What worked, what missed, and what result surprised you?
+  - type: textarea
+    id: friction
+    attributes:
+      label: Friction and docs gaps
+      description: Where did setup, terminology, or the workflow feel confusing?
+  - type: textarea
+    id: crash_report
+    attributes:
+      label: Optional opt-in crash report
+      description: Attach or paste reviewed output from `recallforge crash-report` only if useful.
+      render: json
diff --git a/.github/DISCUSSION_TEMPLATE/beta-feedback.yml b/.github/DISCUSSION_TEMPLATE/beta-feedback.yml
@@ -0,0 +1,48 @@
+title: "[Beta]: "
+labels: ["beta", "feedback"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Beta feedback should focus on release readiness: install, MCP startup, workflow quality, and safe defaults.
+  - type: input
+    id: install_source
+    attributes:
+      label: Install source
+      placeholder: PyPI, release candidate wheel, source checkout
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      placeholder: OS, Python version, backend, MCP client
+    validations:
+      required: true
+  - type: textarea
+    id: workflows
+    attributes:
+      label: Workflows tested
+      description: List the 3-5 real workflows you tried and whether they succeeded.
+    validations:
+      required: true
+  - type: textarea
+    id: flags
+    attributes:
+      label: Feature flags
+      description: Paste `recallforge flags --json` if you changed any defaults.
+      render: json
+  - type: textarea
+    id: quality
+    attributes:
+      label: Quality and performance notes
+      description: Note slow spots, bad matches, missing docs, or release-blocking behavior.
+  - type: checkboxes
+    id: release_readiness
+    attributes:
+      label: Release readiness
+      options:
+        - label: Install was understandable.
+        - label: MCP startup worked in my client.
+        - label: Default feature flags felt safe.
+        - label: I would trust this build for a small local-memory workflow.
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,61 @@
+name: Bug report
+description: Report a reproducible RecallForge bug.
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug. For alpha/beta workflow feedback that is not a reproducible bug, use Discussions instead.
+  - type: textarea
+    id: summary
+    attributes:
+      label: What happened?
+      description: Describe the bug and what you expected instead.
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: Include commands, MCP client, backend, and a tiny fixture if possible.
+      placeholder: |
+        1. Run `recallforge ...`
+        2. Ingest ...
+        3. Search ...
+    validations:
+      required: true
+  - type: dropdown
+    id: surface
+    attributes:
+      label: Surface
+      options:
+        - CLI
+        - MCP stdio
+        - MCP HTTP/SSE
+        - Python API
+        - Storage/indexing
+        - Search/retrieval
+        - Packaging/install
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: RecallForge version
+      placeholder: recallforge --version
+    validations:
+      required: true
+  - type: textarea
+    id: crash_report
+    attributes:
+      label: Optional crash report
+      description: Run `recallforge crash-report --include-env` and paste or attach the reviewed JSON if helpful. Do not include private indexed content.
+      render: json
+  - type: checkboxes
+    id: privacy
+    attributes:
+      label: Privacy check
+      options:
+        - label: I reviewed logs/crash reports for secrets and private indexed content before attaching them.
+          required: true
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Alpha and beta feedback
+    url: https://github.com/brianmeyer/recallforge/discussions
+    about: Use Discussions for workflow reports, install notes, and non-blocking product feedback.
+  - name: Release and testing guide
+    url: https://github.com/brianmeyer/recallforge/blob/master/docs/ALPHA_BETA_TESTING.md
+    about: Read the alpha/beta checklist and opt-in crash-report policy before filing feedback.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,7 @@ All notable changes to RecallForge will be documented in this file.
 - Added staged background reindex promotion so document, video, audio, and conversation replacements stay hidden until their parent/child memory batches are complete.
 - Added index-version-aware query caching for repeated text/media embeddings and generated expansion branches.
 - Added MCP progress notifications for long-running search, ingest, batch, memory write, and FTS rebuild tool calls when clients provide a progress token.
+- Added alpha/beta testing scaffolding with GitHub templates, feature-flag inspection, and local-only opt-in crash report generation.
 - Added deterministic memory graph enrichment with entity/relation side tables and new `memory_graph_entities` / `memory_graph_related` MCP tools.
 - Replaced the tiny UAT video clips with compact episodic-memory fixtures, richer transcript sidecars, related artifact metadata, and regression coverage for the video corpus.
 - Added `memory_add_conversation` so conversation threads ingest as canonical parent memories with turn-level child memories and standard memory rollups.

diff --git a/README.md b/README.md
@@ -265,6 +265,15 @@ Full references:
 [`docs/MEMORY_POLICY.md`](docs/MEMORY_POLICY.md), and
 [`docs/RUNTIME_BUDGETS.md`](docs/RUNTIME_BUDGETS.md)
 
+For alpha/beta testers:
+
+```bash
+recallforge flags
+recallforge crash-report --output recallforge-crash-report.json --message "what happened"
+```
+
+Testing guidance, feature-flag defaults, and the opt-in crash-report policy live in [docs/ALPHA_BETA_TESTING.md](docs/ALPHA_BETA_TESTING.md).
+
 ## Project structure
 
 ```
@@ -280,6 +289,8 @@ src/recallforge/
 ├── documents.py          # PDF/DOCX/PPTX extraction
 ├── video.py              # Frame/transcript extraction
 ├── audio.py              # Transcript-first audio ingest
+├── feature_flags.py      # Alpha/beta feature flag registry
+├── diagnostics.py        # Local-only crash report helpers
 ├── watch_folder.py       # Folder monitoring with dedup
 └── cli.py                # CLI interface
 ```

diff --git a/docs/ALPHA_BETA_TESTING.md b/docs/ALPHA_BETA_TESTING.md
@@ -0,0 +1,126 @@
+# RecallForge Alpha and Beta Testing Program
+
+This program keeps early testing useful without turning a local-first memory tool into silent telemetry. Alpha and beta users should share feedback intentionally through GitHub Discussions or Issues.
+
+## Goals
+
+- Recruit 5-10 alpha users who use RecallForge with real local notes, documents, images, audio, or videos.
+- Validate install, MCP setup, ingest, search, memory rollups, and local runtime safety.
+- Move successful alpha workflows into a broader beta with structured feedback.
+- Keep crash reporting opt-in, inspectable, and manually shared.
+
+## Channels
+
+- Alpha feedback: `https://github.com/brianmeyer/recallforge/discussions`
+- Bug reports: `https://github.com/brianmeyer/recallforge/issues/new/choose`
+- Security issues: use the repository security policy or private maintainer contact, not public Discussions.
+
+GitHub discussion category forms live under `.github/DISCUSSION_TEMPLATE/`. To activate them, enable GitHub Discussions and create categories whose slugs match the template filenames, such as `alpha-feedback` and `beta-feedback`.
+
+## Tester Cohorts
+
+Alpha users should cover:
+
+- Apple Silicon local agents using MLX
+- CPU/CUDA users through the torch backend
+- Claude Desktop or another MCP host
+- text-heavy personal notes
+- multimodal folders with images, PDFs, audio transcripts, and short videos
+
+Beta users should add:
+
+- larger folders and watch-folder workflows
+- repeated reindexing
+- HTTP/SSE MCP clients
+- cross-modal query workflows
+- release-candidate install checks from PyPI
+
+## Feature Flags
+
+Run this to see the supported feature flags and current values:
+
+```bash
+recallforge flags
+recallforge flags --json
+```
+
+Recommended alpha defaults:
+
+- Keep `RECALLFORGE_ENABLE_MEDIA_RERANKING=0` unless a tester is explicitly validating capped media reranking.
+- Keep `RECALLFORGE_ENABLE_RAW_VIDEO_QUERY_EMBEDDING=0` unless validating raw video-query behavior.
+- Keep `RECALLFORGE_ENABLE_MLX_NATIVE_VIDEO_PROCESSING=0` unless validating native MLX video decoding.
+- Use `RECALLFORGE_TRACE=1` only while collecting a diagnostic reproduction.
+
+The canonical environment variable reference is `docs/ENV_VARS.md`.
+
+## Opt-In Crash Reports
+
+RecallForge does not send crash reports automatically. A tester can create a local JSON report and review it before attaching it to a Discussion or Issue:
+
+```bash
+recallforge crash-report --output recallforge-crash-report.json --message "Search crashed after a video query"
+```
+
+To include allowlisted `RECALLFORGE_*` values with home paths redacted:
+
+```bash
+recallforge crash-report --include-env --output recallforge-crash-report.json
+```
+
+Crash reports include:
+
+- RecallForge version
+- Python implementation/version
+- OS family, release, and machine architecture
+- effective feature flag values
+- optional allowlisted `RECALLFORGE_*` environment values
+- a user-provided message
+
+Crash reports do not include:
+
+- indexed content
+- search queries
+- arbitrary environment variables
+- automatic network upload
+- API keys or tokens unless a user manually adds them after generation
+
+## Alpha Checklist
+
+1. Install from PyPI or the current release branch.
+2. Run `recallforge --version`.
+3. Run `recallforge flags --json` and attach the output if testing experimental flags.
+4. Start MCP with `recallforge serve --mode embed`.
+5. Ingest a tiny folder with text plus one media file.
+6. Search text to text, text to media, and media to text.
+7. Reindex the same folder and confirm old/stale results do not appear.
+8. Share feedback through the alpha discussion template.
+
+## Beta Checklist
+
+1. Install from the release candidate wheel or PyPI package.
+2. Run the MCP server through the real client host used day to day.
+3. Ingest a representative local folder.
+4. Run at least five saved workflows:
+   - exact lookup
+   - broad semantic lookup
+   - image query
+   - video or transcript-backed query
+   - conversation or memory rollup lookup
+5. Test one runtime feature flag intentionally, then return to default.
+6. Attach an opt-in crash report only if the run fails.
+7. Record quality and latency notes in the beta discussion template.
+
+## Exit Criteria
+
+Alpha is complete when:
+
+- at least five users complete the alpha checklist
+- no release-blocking install or MCP startup issue remains open
+- crash reports, if any, are reproducible or explicitly accepted as known limitations
+
+Beta is complete when:
+
+- at least ten workflow reports are collected across at least three machine profiles
+- PyPI install and MCP startup are boring
+- docs explain the safest defaults and opt-in flags
+- known limitations are documented before release
diff --git a/docs/ENV_VARS.md b/docs/ENV_VARS.md
@@ -2,6 +2,8 @@
 
 This is the canonical reference for all `RECALLFORGE_*` environment variables used in the codebase.
 
+Run `recallforge flags` to inspect the feature flags that are especially relevant to alpha/beta testers and experimental local workflows.
+
 ## Runtime selection
 
 - `RECALLFORGE_BACKEND`
@@ -77,6 +79,20 @@ This is the canonical reference for all `RECALLFORGE_*` environment variables us
 - `RECALLFORGE_ENABLE_RAW_VIDEO_QUERY_EMBEDDING`
   Enable raw video query embedding. On MLX, RecallForge now defaults to safer caption/transcript-first retrieval unless you explicitly enable this.
 
+## Feature flag surfaces
+
+These variables are intentionally visible through `recallforge flags`:
+
+- `RECALLFORGE_ENABLE_MEDIA_RERANKING`
+- `RECALLFORGE_ENABLE_RAW_VIDEO_QUERY_EMBEDDING`
+- `RECALLFORGE_ENABLE_MLX_NATIVE_VIDEO_PROCESSING`
+- `RECALLFORGE_MEDIA_RERANK_REQUIRE_AMBIGUITY`
+- `RECALLFORGE_MLX_HEAVY_OP_CONCURRENCY`
+- `RECALLFORGE_MCP_MAX_CONCURRENCY`
+- `RECALLFORGE_TRACE`
+
+Alpha/beta users should keep risky media and native-video flags disabled unless they are specifically testing that behavior.
+
 ## Server behavior
 
 - `RECALLFORGE_TRACE`