.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+
+# Project-specific
+~/.marchwarden/
+.env
+.env.local
+*.log
+
+# Tests
+.pytest_cache/
+.coverage
+htmlcov/

CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing to Marchwarden
+
+## Workflow
+
+- **Always branch** — never commit directly to `main`
+- **Branch naming**: `feat/`, `fix/`, `refactor/`, `chore/` + description (e.g., `feat/tavily-integration`)
+- **One branch, one concern** — don't mix unrelated changes
+- **Atomic commits** — each commit is one logical unit; write clear messages
+- **Tests required** — all code changes to testable modules must include or update tests
+- **Test before PR** — run `pytest tests/` and ensure all pass
+
+## Branching
+
+```bash
+# Create a feature branch
+git checkout -b feat/your-feature-name
+
+# Commit logically
+git commit -m "Implement X because Y"
+
+# Push
+git push origin feat/your-feature-name
+```
+
+## Testing
+
+```bash
+# Run all tests
+pytest tests/
+
+# Run with coverage
+pytest --cov=. tests/
+
+# Run a specific test
+pytest tests/test_something.py::test_name
+```
+
+## MCP Contract
+
+Before implementing, read [ResearchContract.md](docs/wiki/ResearchContract.md). The `research()` tool signature is the contract; changes require approval.
+
+## PR process
+
+1. Push your branch
+2. Create a PR on Forgejo
+3. Ensure CI passes (tests, linting)
+4. Request review
+5. Merge via Forgejo API/UI (not locally)
+6. Delete the remote branch
+7. Sync local `main`: `git checkout main && git pull --ff-only`
+
+## Questions?
+
+Check the wiki or open an issue.

README.md

@@ -1,3 +1,49 @@
-# marchwarden
+# Marchwarden
 
-A network of agentic research specialists coordinated by a principal investigator agent. V1: web-search researcher MCP server + CLI shim.
+A network of agentic research specialists coordinated by a principal investigator agent.
+
+Marchwarden researchers are stationed at the frontier of knowledge — they watch, search, synthesize, and report back what they find. Each specialist is self-contained, fault-tolerant, and exposed via MCP. The PI agent orchestrates them to answer complex, multi-domain questions.
+
+**V1**: Single web-search researcher + CLI shim for development.  
+**V2+**: Multiple specialists (arxiv, database, internal docs, etc.) + PI orchestrator.
+
+## Quick start
+
+```bash
+# Clone
+git clone https://forgejo.labbity.unbiasedgeek.com/claude-code/marchwarden.git
+cd marchwarden
+
+# Install
+pip install -e .
+
+# Ask a question
+marchwarden ask "What are ideal crops for a garden in Utah?"
+
+# Replay a research session
+marchwarden replay <trace_id>
+```
+
+## Documentation
+
+- **[Architecture](docs/wiki/Architecture.md)** — system design, researcher contract, MCP flow
+- **[Development Guide](docs/wiki/DevelopmentGuide.md)** — setup, running tests, debugging
+- **[Research Contract](docs/wiki/ResearchContract.md)** — the `research()` tool specification
+- **[Contributing](CONTRIBUTING.md)** — branching, commits, PR workflow
+
+## Status
+
+- V1 scope: [Issue #1](https://forgejo.labbity.unbiasedgeek.com/claude-code/marchwarden/issues/1)
+- Branch: `main` (development)
+- Tests: `pytest tests/`
+
+## Stack
+
+- **Language**: Python 3.10+
+- **Agent framework**: [Anthropic Claude Agent SDK](https://github.com/anthropics/anthropic-sdk-python)
+- **MCP server**: [Model Context Protocol](https://modelcontextprotocol.io)
+- **Web search**: Tavily API
+
+## License
+
+(TBD)

pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "marchwarden"
+version = "0.1.0-dev"
+description = "Agentic research network: specialists at the frontier, PI orchestrator at the center"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    {name = "archeious"}
+]
+
+dependencies = [
+    "anthropic>=0.30.0",
+    "mcp>=0.1.0",
+    "pydantic>=2.0",
+    "tavily-python>=0.3.0",
+    "httpx>=0.24.0",
+    "click>=8.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "black>=23.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0",
+]
+
+[project.scripts]
+marchwarden = "cli.main:cli"
+
+[tool.setuptools.packages.find]
+include = ["researchers*", "orchestrator*", "cli*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+
+[tool.coverage.run]
+source = ["researchers", "orchestrator", "cli"]
+omit = ["*/tests/*", "*/test_*.py"]
+
+[tool.black]
+line-length = 88
+target-version = ['py310']
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+select = ["E", "F", "W", "I001"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false