docs: add contributing guide and per-package release workflows

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,15 +1,13 @@
-## Summary
+## What does this PR do?
 
-<!-- What does this PR do? Keep it short. -->
+<!-- A short description. Link to an issue if relevant: Fixes #123 -->
 
-## Changes
+## How to test
 
-- 
+<!-- How can a reviewer verify this works? -->
 
-## Test Plan
+## Checklist
 
-- [ ] `pytest packages/mcp-forge-core/tests/` passes
-- [ ] `pytest packages/mcp-forge-aws/tests/` passes
-- [ ] `pytest packages/mcp-forge-cli/tests/` passes
+- [ ] Tests added or updated
 - [ ] `ruff check packages/` passes
-- [ ] No business-specific references in source code
+- [ ] `pytest` passes for affected package(s)

.github/workflows/release-aws.yml

@@ -0,0 +1,21 @@
+name: Release AWS
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build packages/mcp-forge-aws
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: packages/mcp-forge-aws/dist/

.github/workflows/release-cli.yml

@@ -0,0 +1,21 @@
+name: Release CLI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build packages/mcp-forge-cli
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: packages/mcp-forge-cli/dist/

.github/workflows/release-core.yml

@@ -0,0 +1,21 @@
+name: Release Core
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build packages/mcp-forge-core
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: packages/mcp-forge-core/dist/

CONTRIBUTING.md

@@ -1,32 +1,89 @@
 # Contributing to mcp-forge
 
-## Quick Start
+We'd love your help making mcp-forge better. Whether it's a bug fix, new provider, or documentation improvement — all contributions are welcome.
+
+## Getting Started
 
 ```bash
-git clone https://github.com/CoreNovus/mcp-forge.git
+# 1. Fork this repo on GitHub, then:
+git clone git@github.com:<your-username>/mcp-forge.git
 cd mcp-forge
+
+# 2. Install everything
 pip install -e packages/mcp-forge-core[dev]
 pip install -e packages/mcp-forge-aws[dev]
 pip install -e packages/mcp-forge-cli[dev]
+
+# 3. Make sure it works
+ruff check packages/
+pytest packages/mcp-forge-core/tests/
+pytest packages/mcp-forge-aws/tests/
+pytest packages/mcp-forge-cli/tests/
+```
+
+That's it. You're ready to contribute.
+
+## How to Contribute
+
+### 1. Pick something to work on
+
+- Browse [open issues](https://github.com/CoreNovus/mcp-forge/issues)
+- Look for `good first issue` labels if this is your first contribution
+- Or just fix something that bothers you
+
+### 2. Create a branch and make your changes
+
+```bash
+git checkout -b feat/your-idea       # feature
+git checkout -b fix/what-you-fixed   # bug fix
+git checkout -b docs/what-you-added  # docs
+```
+
+### 3. Write tests
+
+Every change needs tests. We aim for real boundary testing — not just happy paths:
+
+```python
+# Good: tests the edge case
+async def test_cache_empty_string_key(self, cache):
+    await cache.put("", {"v": 1})
+    assert await cache.get("") == {"v": 1}
+
+# Good: tests error behavior
+async def test_unknown_type_raises(self):
+    with pytest.raises(ValueError, match="Unknown"):
+        await provider.extract(b"img", "nonexistent")
+```
+
+### 4. Run checks, then open a PR
+
+```bash
+ruff check packages/                      # lint
+pytest packages/mcp-forge-core/tests/     # core tests
+pytest packages/mcp-forge-aws/tests/      # aws tests
+pytest packages/mcp-forge-cli/tests/      # cli tests
 ```
 
-## Workflow
+Push your branch, open a PR, and fill in the template. CI runs automatically — once it's green and reviewed, we'll merge it.
+
+## What Goes Where
+
+| Package | What belongs here |
+|---------|------------------|
+| **mcp-forge-core** | Provider ABCs, config, server factory, ToolContext, decorators, resilience patterns. Pure Python, zero cloud dependencies. |
+| **mcp-forge-aws** | AWS-specific implementations. Depends on boto3. |
+| **mcp-forge-cli** | Scaffold CLI and Jinja2 templates. |
+
+## Things to Keep in Mind
+
+**Framework, not application.** mcp-forge is used by many different MCP servers. Don't add code that assumes a specific use case (document processing, image analysis, etc.).
 
-1. Fork the repo
-2. Create a branch from `main`
-3. Make changes, add tests
-4. Run `ruff check packages/` and `pytest`
-5. Open a PR — CI must pass and 1 review is required
+**Provider ABCs are domain-agnostic.** Infrastructure providers (Cache, Session, Telemetry) are top-level exports. Capability providers (Vision, Transcribe) exist for swappability but are direct-import only — the framework doesn't assume everyone needs them.
 
-## Rules
+**Tests matter.** We test boundaries: empty input, unicode, TTL expiry, error propagation, concurrent access. If you find an untested edge case, that's a great first PR.
 
-- Every PR needs tests
-- `ruff check` must pass
-- No business-specific code — this is a generic framework
-- Keep provider ABCs domain-agnostic
+**Keep it simple.** If your change adds complexity, make sure it solves a real problem. Three lines of clear code beats a clever abstraction.
 
-## Package Structure
+## Questions?
 
-- `mcp-forge-core` — infrastructure providers, patterns, server factory
-- `mcp-forge-aws` — AWS implementations (Bedrock, DynamoDB, CloudWatch)
-- `mcp-forge-cli` — scaffold CLI tool
+Open an [issue](https://github.com/CoreNovus/mcp-forge/issues). There are no dumb questions.