Add documents for agent collaboration

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,38 +1,31 @@
 ---
-name: Bug report
-about: Create a report to help us improve
-title: ''
-labels: ''
-assignees: ''
+name: 🐞 Bug Report
+about: Report a bug to help us improve
+title: 'Bug: [Short description]'
+labels: 'fixme'
+assignees: 'alexnodeland'
 
 ---
 
-**Describe the bug**
+## Describe the bug
+
 A clear and concise description of what the bug is.
 
-**To Reproduce**
-Steps to reproduce the behavior:
+## Steps To Reproduce
+
 1. Go to '...'
 2. Click on '....'
 3. Scroll down to '....'
 4. See error
 
-**Expected behavior**
+## Expected behavior
+
 A clear and concise description of what you expected to happen.
 
-**Screenshots**
-If applicable, add screenshots to help explain your problem.
+## Actual behavior
 
-**Desktop (please complete the following information):**
- - OS: [e.g. iOS]
- - Browser [e.g. chrome, safari]
- - Version [e.g. 22]
+A clear and concise description of what actually happened.
 
-**Smartphone (please complete the following information):**
- - Device: [e.g. iPhone6]
- - OS: [e.g. iOS8.1]
- - Browser [e.g. stock browser, safari]
- - Version [e.g. 22]
+## Additional Context
 
-**Additional context**
 Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,20 +1,24 @@
 ---
-name: Feature request
+name: 💡 Feature Request
 about: Suggest an idea for this project
-title: ''
-labels: ''
-assignees: ''
+title: 'Feature: [Short description]'
+labels: 'enhancement'
+assignees: 'alexnodeland'
 
 ---
 
-**Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+## Is your feature request related to a problem?
+
+Please provide a clear and concise description of what the problem is. Ex. I'm always frustrated when [...] If not, just write "None".
+
+## Describe the solution you'd like
 
-**Describe the solution you'd like**
 A clear and concise description of what you want to happen.
 
-**Describe alternatives you've considered**
+## Describe alternatives you've considered
+
 A clear and concise description of any alternative solutions or features you've considered.
 
-**Additional context**
+## Additional context
+
 Add any other context or screenshots about the feature request here.

.github/ISSUE_TEMPLATE/rfc.md

@@ -0,0 +1,37 @@
+---
+name: "💡 RFC Proposal"
+about: Submit a Request for Comments (RFC) to propose a design or feature
+title: "RFC: [short descriptive title]"
+labels: ["rfc/draft"]
+assignees: ""
+---
+
+## Summary
+
+One-paragraph explanation of the proposal.
+
+## Motivation
+
+- What problem does this solve?
+- Why is this important?
+
+## Proposed Solution
+
+- Outline the design at a high level.
+- Include diagrams, data flows, or API examples if helpful.
+
+## Alternatives Considered
+
+- What other options did you consider and reject?
+
+## Risks / Drawbacks
+
+- Known trade-offs or risks.
+
+## Open Questions
+
+- What needs further discussion?
+
+---
+
+🔗 **RFC File:** Create a corresponding markdown file in `/docs/rfcs/` with more details, and open a PR, discuss in comments, then merge and create implmenetation issue(s).

.github/PULL_REQUEST_TEMPLATE/adr.md

@@ -0,0 +1,25 @@
+# ADR Pull Request
+
+## ADR Info
+
+- **ADR Number:** [leave empty until assigned]
+- **Title:** [decision title]
+- **Status:** Proposed
+- **Author(s):** [GitHub Username(s)]
+- **Supersedes:** ADR-XXX [if applicable]
+- **Linked RFC:** RFC-XXX
+
+---
+
+## Summary
+
+Concise summary of the decision.
+
+---
+
+### Checklist
+
+- [ ] ADR file created under `/docs/adrs/NNN-decision-title.md`
+- [ ] Metadata filled in (authors, date, status)
+- [ ] Links to related RFCs and Issues
+- [ ] Labels applied (`adr`)

.github/PULL_REQUEST_TEMPLATE/rfc.md

@@ -0,0 +1,29 @@
+# RFC Pull Request
+
+## RFC Info
+
+- **RFC Number:** [leave empty until assigned]
+- **Title:** [short descriptive title]
+- **Status:** Draft
+- **Author(s):** [GitHub Username(s)]
+- **Linked Issue:** #[issue number if any]
+
+---
+
+## Summary
+
+Brief summary of the RFC included in this PR.
+
+## Notes for Reviewers
+
+- What parts need extra scrutiny?
+- Any alternatives the reviewers should consider?
+
+---
+
+### Checklist
+
+- [ ] RFC file created under `/docs/rfcs/NNN-title.md`
+- [ ] Metadata filled in (authors, date, status)
+- [ ] Proposal reviewed for clarity
+- [ ] Labels applied (`rfc/draft`)

.github/workflows/publish.yml

@@ -18,6 +18,7 @@ jobs:
         uses: dtolnay/rust-toolchain@stable
 
       - name: Check if version is already published
+        id: version_check
         run: |
           # Get the workspace package info (not dependencies)
           WORKSPACE_ROOT=$(cargo metadata --format-version=1 | jq -r '.workspace_root')
@@ -32,12 +33,14 @@ jobs:
 
           if echo "$DRY_RUN_OUTPUT" | grep -q "already exists on crates.io index"; then
             echo "Version $PACKAGE_VERSION of $PACKAGE_NAME already exists on crates.io. Skipping publish."
-            exit 0
+            echo "should_publish=false" >> $GITHUB_OUTPUT
           else
             echo "Version $PACKAGE_VERSION of $PACKAGE_NAME can be published. Proceeding with publish."
+            echo "should_publish=true" >> $GITHUB_OUTPUT
           fi
 
       - name: Publish to crates.io
+        if: steps.version_check.outputs.should_publish == 'true'
         run: cargo publish --allow-dirty
         env:
           CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}

AGENTS.md

@@ -0,0 +1,157 @@
+# Agent Context: Fugue Probabilistic Programming Library
+
+## Project Overview
+
+Fugue is a **production-ready, monadic probabilistic programming library** for Rust. It enables elegant probabilistic program composition through `Model` values executed with pluggable interpreters and state-of-the-art inference algorithms.
+
+### Core Philosophy
+
+- **Monadic Design**: Compose probabilistic programs using pure functional abstractions
+- **Type Safety**: Natural return types for distributions (Bernoulli → `bool`, Poisson → `u64`)  
+- **Production Ready**: Numerically stable algorithms with comprehensive error handling
+- **Performance Focused**: Memory optimization, copy-on-write traces, efficient algorithms
+
+## Architecture Overview
+
+```text
+fugue/
+├── src/           # Core library implementation
+│   ├── core/      # Fundamental PPL primitives (Model, Distribution, Address)
+│   ├── runtime/   # Execution engine (Handlers, Interpreters, Traces)
+│   ├── inference/ # Algorithms (MCMC, SMC, VI, ABC)
+│   └── error.rs   # Comprehensive error handling
+├── docs/          # User documentation (mdbook)
+├── examples/      # Practical usage examples
+├── tests/         # Integration and API tests
+└── benches/       # Performance benchmarks
+```
+
+## Key Concepts
+
+### Model Composition
+
+- `Model<T>`: Core probabilistic program type
+- `sample()`: Draw from distributions  
+- `observe()`: Condition on data
+- `prob!` macro: Do-notation for monadic composition
+
+### Address System
+
+- Every random choice has a unique, stable address
+- Format: `"name"`, `"name#index"`, `"scope::name"`, `"scope::name#index"`
+- Critical for reproducibility and inference targeting
+
+### Interpreters/Handlers
+
+- `PriorHandler`: Forward sampling from priors
+- `ReplayHandler`: Replay with specific trace values
+- `ScoreGivenTrace`: Score traces for importance sampling
+- Safe variants available for production use
+
+## Development Guidelines
+
+### Mandatory Testing Practice
+
+**Always run tests after making changes.** This is critical for a probabilistic programming library where subtle changes can have significant statistical implications.
+
+```bash
+# Always run before committing changes
+make all
+
+# For quick feedback during development
+make test
+
+# Check test coverage
+make coverage
+```
+
+### Code Style
+
+- Follow standard Rust conventions (rustfmt, clippy)
+- Prefer explicit error handling over panics
+- Use type-safe abstractions over raw implementations
+- Document public APIs with examples
+
+### Testing Patterns
+
+- Unit tests for individual components
+- Integration tests for end-to-end workflows  
+- Property-based testing for numerical stability
+- Benchmark critical performance paths
+
+### Domain-Specific Considerations
+
+- **Numerical Stability**: Use log-space computations, guard against overflow/underflow
+- **Reproducibility**: Ensure deterministic execution given same random seed
+- **Memory Management**: Consider trace pooling for high-throughput applications
+- **Error Propagation**: Preserve error context through the computation stack
+
+## Common Tasks
+
+### Adding New Distributions
+
+1. Implement `Distribution<T>` trait in `src/core/distribution.rs`
+2. Add validation logic and error handling
+3. Include comprehensive tests with edge cases
+4. Document mathematical properties and use cases
+
+### Implementing Inference Algorithms
+
+1. Design around existing `Handler` infrastructure
+2. Consider trace manipulation patterns
+3. Implement convergence diagnostics
+4. Provide both basic and production-ready variants
+
+### Performance Optimization
+
+1. Profile with realistic workloads first
+2. Consider memory pooling for frequent allocations
+3. Use copy-on-write semantics where appropriate
+4. Benchmark against baseline implementations
+
+## Development Tools
+
+- `make test`: Run test suite
+- `make lint`: Run clippy linter
+- `make fmt`: Format code
+- `make doc`: Generate and open documentation
+- `make mdbook`: Build mdbook documentation
+- `make coverage`: Generate coverage report
+- `make bench`: Run benchmarks
+- `make all`: Run all checks (format, lint, test, coverage)
+
+## Getting Started
+
+```bash
+# Build and test
+make test
+
+# Run examples
+cargo run --example basic_modeling
+
+# Generate documentation  
+make docs-all
+
+# Format and lint
+make fmt
+make lint
+
+# Run all checks
+make all
+```
+
+## Critical Areas Requiring Domain Knowledge
+
+1. **Probabilistic Programming Theory**: Understanding of measure theory, inference algorithms
+2. **Numerical Analysis**: Floating-point precision, log-space computations  
+3. **Rust Systems Programming**: Memory management, zero-cost abstractions
+4. **Statistical Computing**: Convergence diagnostics, sampling strategies
+
+## Contribution Guidelines
+
+- Changes should preserve API compatibility where possible
+- New features require comprehensive tests and documentation
+- Performance-critical changes need benchmark validation
+- All public APIs must include usage examples
+
+For detailed contribution guidelines, see `.github/CONTRIBUTING.md`.

README.md

@@ -1,17 +1,25 @@
+<div align="center">
+
 # 🎼 Fugue
 
+<img src="assets/fugue-logo.svg" alt="Fugue Logo" width="200" height="200">
+
+**A production-ready, monadic probabilistic programming library for Rust**
+
+*Write elegant probabilistic programs by composing `Model` values in direct style; execute them with pluggable interpreters and state-of-the-art inference algorithms.*
+
 [![Rust](https://img.shields.io/badge/rust-1.70%2B-blue.svg)](https://www.rust-lang.org)
 [![Crates.io](https://img.shields.io/crates/v/fugue-ppl.svg)](https://crates.io/crates/fugue-ppl)
 [![Dev Docs](https://docs.rs/fugue-ppl/badge.svg)](https://docs.rs/fugue-ppl)
 [![User Docs](https://img.shields.io/badge/guides-fugue.run-blue)](https://fugue.run)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/alexnodeland/fugue/actions/workflows/ci-develop.yml/badge.svg)](https://github.com/alexnodeland/fugue/actions/workflows/ci-develop.yml)
 [![codecov](https://codecov.io/gh/alexnodeland/fugue/branch/develop/graph/badge.svg?token=BDJ5OB6GOB)](https://codecov.io/gh/alexnodeland/fugue)
+[![Discord](https://img.shields.io/discord/1412802057437712426?logo=discord&label=discord)](https://discord.gg/QAcF7Nwr)
 
+**Supported Rust:** 1.70+ • **Platforms:** Linux / macOS / Windows • **Crate:** [`fugue-ppl` on crates.io](https://crates.io/crates/fugue-ppl)
 
-A **production-ready**, **monadic probabilistic programming library** for Rust. Write elegant probabilistic programs by composing `Model` values in direct style; execute them with pluggable interpreters and state-of-the-art inference algorithms.
-
-> Supported Rust: 1.70+ • Platforms: Linux / macOS / Windows • Crate: [`fugue-ppl` on crates.io](https://crates.io/crates/fugue-ppl)
+</div>
 
 ## ✨ Features
 
@@ -75,6 +83,7 @@ let mu_values: Vec<f64> = samples.iter()
 
 - **Issues & Bugs**: Use [GitHub Issues](https://github.com/alexnodeland/fugue/issues)
 - **Feature Requests**: Open an issue with the `enhancement` label
+- **Discord**: Join our [Discord server](https://discord.gg/QAcF7Nwr)
 
 ## 🗺️ Roadmap