update

CONTRIBUTING.md

@@ -1,33 +1,111 @@
-# Devour
+# Contributing to Devour
 
-Devour is a context ingestion and management system for AI that scrapes, indexes, and serves documentation from multiple sources.
+Thanks for considering a contribution.
 
-## Installation
+Devour is moving fast, and practical contributions (bug fixes, docs cleanup, tests, stability work) are especially valuable right now.
+
+## Before You Start
+
+- Check existing issues/PRs to avoid duplicate work.
+- If the change is non-trivial, open an issue first to align on direction.
+- Keep PRs focused. Small, reviewable changes get merged faster.
+
+## Local Setup
 
 ```bash
-go install github.com/yourorg/devour/cmd/devour@latest
+git clone <your-fork-or-repo-url>
+cd devour
+go mod download
+go build -o devour ./cmd/devour
 ```
 
-## Quick Start
+Optional sanity check:
 
 ```bash
-# Initialize
-devour init
-
-# Scrape documentation
-devour scrape https://docs.example.com
-
-# Query indexed docs
-devour query "authentication flow"
-
-# Start MCP server
-devour serve
+./devour --help
 ```
 
-## Documentation
+## Branch and Commit Workflow
 
-See [README.md](README.md) for full documentation.
+1. Fork the repo.
+2. Create a branch from `main`:
+   `git checkout -b feat/short-description`
+3. Make your changes.
+4. Run tests/checks.
+5. Commit with a clear message.
+6. Open a PR.
 
-## License
+Commit style suggestion:
 
-MIT License
+- `feat: add xyz`
+- `fix: resolve panic in abc`
+- `docs: clarify quick start`
+- `test: add coverage for module`
+
+## What To Test
+
+At minimum, run:
+
+```bash
+go test ./...
+```
+
+If your changes affect CLI behavior, also run relevant commands directly (for example `devour get`, `devour ask`, `devour quality status`).
+
+If you touch docs, verify commands and paths are real.
+
+## Current Known Limitations
+
+Please keep these in mind when proposing fixes or documentation:
+
+- Remote workflows are still experimental:
+  - `devour serve --remote` is available, but local stdio JSON-RPC is the primary stable mode.
+  - remote `push` flows are intentionally disabled in stable behavior.
+- Live scraping quality can vary with upstream site changes; use `devour verify smoke` before releases.
+- Language support is broad, but extraction quality differs by source type and site structure.
+- Quality analyzers are strongest for Go code; cross-language analysis remains limited.
+
+PRs that improve these areas are highly appreciated.
+
+## Pull Request Checklist
+
+Before opening a PR, confirm:
+
+- [ ] Change is scoped and clearly described.
+- [ ] Tests pass locally (`go test ./...`).
+- [ ] New behavior includes tests when feasible.
+- [ ] Docs updated for user-facing changes.
+- [ ] No unrelated refactors mixed in.
+
+## Coding Guidelines
+
+- Follow existing Go style in the touched package.
+- Prefer clear, simple control flow over clever abstractions.
+- Add comments only when they explain non-obvious intent.
+- Preserve current CLI UX unless there is a strong reason to change it.
+
+## Reporting Bugs
+
+When filing a bug, include:
+
+- Devour command used
+- exact error output
+- OS and Go version
+- minimal reproduction steps
+
+Bug reports with reproducible steps are fixed much faster.
+
+## Documentation Contributions
+
+Docs improvements are first-class contributions.
+
+Useful docs PRs include:
+
+- fixing incorrect command examples
+- clarifying status of in-progress features
+- adding troubleshooting notes
+- improving onboarding for first-time contributors
+
+## Questions
+
+If something is unclear, open an issue and ask directly. It is better to align early than rework a large PR later.