[Spec 13] OSS Readiness for Early Adopters — v0.4.0

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,89 @@
+name: Bug Report
+description: Report a bug or unexpected behavior in FAVA Trails
+labels: [bug]
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please fill out the fields below to help us diagnose the issue.
+
+        **Note:** Security vulnerabilities should be reported privately via [GitHub Security Advisories](https://github.com/MachineWisdomAI/fava-trails/security/advisories/new), not as public issues.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear, concise description of the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: Step-by-step instructions to reproduce the behavior.
+      placeholder: |
+        1. Configure MCP server with ...
+        2. Call tool `recall(trail_name="...", query="...")`
+        3. See error ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened? Include any error messages or stack traces.
+    validations:
+      required: true
+
+  - type: input
+    id: jj-version
+    attributes:
+      label: JJ Version
+      description: Output of `jj --version`
+      placeholder: "jj 0.28.0"
+    validations:
+      required: true
+
+  - type: input
+    id: fava-trails-version
+    attributes:
+      label: FAVA Trails Version
+      description: Output of `pip show fava-trails | grep Version` or the version from your uv.lock
+      placeholder: "0.4.0"
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating System
+      description: Your OS and version
+      placeholder: "macOS 15.2 / Ubuntu 24.04 / Windows 11"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version
+      description: Output of `python --version`
+      placeholder: "3.11.9"
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other context, config snippets, or screenshots that might help.

.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write      # Required for OIDC Trusted Publishing
+  attestations: write  # Required for SLSA provenance attestations
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.11"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true

.github/workflows/test.yml

@@ -0,0 +1,34 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install JJ
+        run: |
+          bash scripts/install-jj.sh
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: Lint
+        run: uv run ruff check src/ tests/
+
+      - name: Run tests
+        run: uv run pytest -v
+        env:
+          JJ_CONFIG: /dev/null

CHANGELOG.md

@@ -0,0 +1,89 @@
+# Changelog
+
+All notable changes to FAVA Trails are documented here.
+
+## [0.4.0] — 2026-02-24
+
+### Added
+- **Rebrand**: Project renamed from `fava-trail` to `fava-trails` (package, module, entry point)
+- **OSS readiness**: Apache 2.0 license declared in pyproject.toml, CONTRIBUTING.md, CHANGELOG.md, SECURITY.md
+- **GitHub Actions CI**: Automated test + lint on every push and pull request
+- **Issue templates**: Bug report template with JJ/OS/Python version fields
+- **PyPI publishing workflow**: Added Trusted Publishing GitHub Actions workflow for tag-based releases (`pip install fava-trails` available after first publish)
+- **Full pyproject.toml metadata**: license, authors, readme, classifiers, project URLs
+
+### Changed
+- Version bumped to 0.4.0 (first public release post-rebrand)
+
+### Upgrading from fava-trail to fava-trails
+
+If you were using the previous `fava-trail` package:
+
+| Before | After |
+|--------|-------|
+| `pip install fava-trail` | `pip install fava-trails` |
+| `import fava_trail` | `import fava_trails` |
+| `fava-trail-server` (entry point) | `fava-trails-server` (entry point) |
+
+Update your MCP configuration:
+```json
+{
+  "mcpServers": {
+    "fava-trails": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/fava-trails", "fava-trails-server"]
+    }
+  }
+}
+```
+
+---
+
+## [0.3.3] — 2026-02-10
+
+### Fixed
+- Scope discovery reliability: `.fava-trail.yaml` now correctly propagates scope to `.env` for all agents in a project
+- CLI spec improvements for `fava-trails-server` startup behavior
+
+---
+
+## [0.3.2] — 2026-01-28
+
+### Added
+- `get_usage_guide` MCP tool: returns full protocol reference on-demand
+- MCP server `instructions` field: auto-injects core usage guidance at session start for all MCP clients that support it
+
+---
+
+## [0.3.1] — 2026-01-15
+
+### Added
+- Multi-scope search in `recall`: `trail_names` parameter accepts glob patterns (e.g., `mw/eng/*`)
+- Preferences auto-surface: user preference thoughts automatically included in relevant recall results
+
+---
+
+## [0.3.0] — 2025-12-20
+
+### Added
+- Storage substrate amendments: monorepo support for shared FAVA Trails data repos
+- Conflict interception: JJ conflicts in data repos are detected and surfaced to agents before they cause silent data loss
+
+---
+
+## [0.2.0] — 2025-11-10
+
+### Added
+- Trust Gate: recalled thoughts pass through a configurable trust review before being returned to agents
+- Hierarchical scoping: trail names use slash-separated paths (e.g., `org/project/epic`) with inheritance
+
+---
+
+## [0.1.0] — 2025-10-01
+
+### Added
+- Initial release: 15 MCP tools for agent memory management
+- VCS-backed storage using Jujutsu (JJ) colocated git repos
+- Draft/promoted thought lifecycle (`save_thought` → `propose_truth`)
+- Full thought lineage tracking (who wrote it, when, why it changed)
+- Engine/Fuel split architecture: stateless MCP server + separate user-controlled data repo

CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing to FAVA Trails
+
+Thank you for your interest in contributing! This guide covers everything you need to get started.
+
+## Prerequisites
+
+- **Python 3.11+** — [python.org](https://www.python.org/downloads/)
+- **JJ (Jujutsu)** — required for running tests (FAVA Trails uses JJ as its VCS engine)
+- **uv** — Python package manager ([docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/))
+
+### Install JJ
+
+```bash
+bash scripts/install-jj.sh
+```
+
+This downloads a pre-built binary for your platform (Linux x86_64 or aarch64) to `~/.local/bin/jj`. Make sure `~/.local/bin` is in your `PATH`.
+
+## Setup
+
+```bash
+# Clone the repo
+git clone https://github.com/MachineWisdomAI/fava-trails.git
+cd fava-trails
+
+# Install dependencies (including dev tools)
+uv sync
+```
+
+## Running Tests
+
+```bash
+uv run pytest -v
+```
+
+Tests create temporary JJ repositories in isolated directories — no external data repo required.
+
+## Linting
+
+```bash
+uv run ruff check src/ tests/
+```
+
+All PRs must pass ruff with zero errors.
+
+## Making Changes
+
+1. Fork the repo and create a branch: `git checkout -b fix/my-fix`
+2. Make your changes
+3. Run tests and linting to verify everything passes
+4. Push your branch and open a pull request
+
+## PR Expectations
+
+- Tests pass (`uv run pytest -v` exits 0)
+- Lint passes (`uv run ruff check src/ tests/` exits 0)
+- Descriptive commit messages (what changed and why)
+- One logical change per PR — keep PRs focused
+
+## About the `codev/` Directory
+
+The `codev/` directory contains the internal development methodology (specs, plans, reviews) used by the Machine Wisdom team. External contributors are **not expected** to use or understand these files — they're here for transparency. Your PR does not need a spec or plan document.
+
+## Reporting Issues
+
+Use the [bug report template](https://github.com/MachineWisdomAI/fava-trails/issues/new?template=bug_report.yml). Include your JJ version (`jj --version`), OS, Python version, and steps to reproduce.
+
+For security vulnerabilities, please use [GitHub Security Advisories](https://github.com/MachineWisdomAI/fava-trails/security/advisories/new) — do not file public issues for security bugs.

README.md

@@ -74,13 +74,13 @@ For Claude Desktop on Windows (accessing WSL):
 Agents call MCP tools. Core workflow:
 
 ```
-save_thought("My finding about X", source_type="observation")
+save_thought(trail_name="myorg/eng/my-project", content="My finding about X", source_type="observation")
   → creates a draft in drafts/
 
-propose_truth(thought_id)
+propose_truth(trail_name="myorg/eng/my-project", thought_id=thought_id)
   → promotes to observations/ (visible to all agents)
 
-recall(query="X")
+recall(trail_name="myorg/eng/my-project", query="X")
   → finds the promoted thought
 ```
 
@@ -179,3 +179,9 @@ uv run pytest --cov       # with coverage
 - [AGENTS_USAGE_INSTRUCTIONS.md](AGENTS_USAGE_INSTRUCTIONS.md) — Canonical usage: scope discovery, session protocol, agent identity
 - [AGENTS_SETUP_INSTRUCTIONS.md](AGENTS_SETUP_INSTRUCTIONS.md) — Data repo setup, config reference, trust gate prompts
 - [docs/fava_trail_faq.md](docs/fava_trail_faq.md) — Detailed FAQ for framework authors and ML engineers
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions, how to run tests, and PR expectations.
+
+See [CHANGELOG.md](CHANGELOG.md) for release history. If you're upgrading from `fava-trail`, see the [0.4.0 upgrade notes](CHANGELOG.md#040--2026-02-24).

SECURITY.md

@@ -0,0 +1,25 @@
+# Security Policy
+
+## Supported Versions
+
+| Component | Minimum Supported Version |
+|-----------|--------------------------|
+| FAVA Trails | 0.4.0+ |
+| Python | 3.11+ |
+| JJ (Jujutsu) | 0.28.0+ |
+
+Older versions do not receive security updates. Please upgrade to the latest release.
+
+## Reporting a Vulnerability
+
+**Do not report security vulnerabilities via public GitHub Issues.**
+
+Please use [GitHub Security Advisories](https://github.com/MachineWisdomAI/fava-trails/security/advisories/new) to report vulnerabilities privately. This allows us to investigate and prepare a fix before public disclosure.
+
+Include in your report:
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if any)
+
+We will acknowledge your report within 48 hours and aim to release a fix within 14 days for critical issues.

af-config.json

@@ -0,0 +1 @@
+{"shell":{"architect":"claude --dangerously-skip-permissions","builder":"claude --model sonnet --dangerously-skip-permissions","shell":"bash"}}