diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8238d8c..dfc6cd9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,5 +1,70 @@
 # Contributing
 
+Thanks for helping improve `ctxd`. This guide covers the local development
+workflow, pull request expectations, and release notes specific to this
+repository.
+
+## Development Setup
+
+Clone the repository, then install the project and development dependencies with
+`uv`:
+
+```bash
+uv sync
+```
+
+Verify the CLI is available through the local environment:
+
+```bash
+uv run ctxd --version
+```
+
+This project supports Python 3.11 and 3.12.
+
+## Running Tests
+
+Run the test suite before opening a pull request:
+
+```bash
+uv run pytest tests -v
+```
+
+Add or update tests when changing SDK behavior, CLI behavior, configuration
+handling, or error handling.
+
+## Pull Requests
+
+Keep pull requests focused on one change or closely related set of changes.
+Before opening a PR:
+
+- Create a branch for the change.
+- Add or update tests for behavior changes.
+- Update `README.md` or other docs for user-facing changes.
+- Run `uv run pytest tests -v`.
+- Mention any tests you could not run in the PR description.
+
+Maintainers may ask for revisions before merging. Documentation-only PRs usually
+do not need a package version bump.
+
+## Bug Reports and Feature Requests
+
+When filing a bug report, include:
+
+- The installed `ctxd` version.
+- Your Python version and operating system.
+- The command or code snippet that reproduces the issue.
+- Expected behavior and actual behavior.
+- Relevant traceback or command output.
+
+For feature requests, describe the use case, the current limitation, and the
+interface affected, such as the Python SDK, CLI, MCP, or REST API.
+
+## Security Reports
+
+Do not open a public issue for security vulnerabilities, leaked credentials, or
+bugs that could expose private data. Contact the maintainers privately with the
+details and enough information to reproduce or assess the issue.
+
 ## Bumping the Package Version
 
 The package version is defined in `pyproject.toml` in two places:
@@ -8,7 +73,8 @@ The package version is defined in `pyproject.toml` in two places:
 - `tool.bumpversion.current_version`
 
 PyPI does not allow re-publishing the same version. Any PR that should publish a
-new package must bump both values to the next version before merging.
+new package must bump both values to the next version before merging. Maintainers
+may ask for a version bump when a change should be released to PyPI.
 
 ### Manual Version Bump
 
diff --git a/README.md b/README.md
index c7ae8e8..78f0227 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,8 @@ Python SDK and CLI for the `ctxd` platform.
 
 CTXD is cloud context infrastructure for AI agents. It connects to cloud files and data across apps such as Google Drive, Slack, GitHub, and Google Calendar, then parses, indexes, and syncs that content so it can be searched from the same permission-aware index through the Python SDK, CLI, MCP, or REST API.
 
+For a fuller introduction, see the [CTXD docs overview](https://ctxd.dev/docs/overview/).
+
 Install:
 
 ```bash