docs: add CONTRIBUTING.md and examples/ structure

- Add CONTRIBUTING.md with language policy, commit conventions,
  project structure, and PR checklist
- Move docker/ckan-mcp-bridge.js → examples/ollama-chat/
- Add examples/ollama-chat/README.md
- Update docker/README.md to point to the example
- Update .gitignore with examples/ policy comment

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: aborruso

.gitignore

@@ -64,6 +64,8 @@ gha-creds-*.json
 docs/video/
 nanobanana-output/
 README.bak.md
+# examples/ contains tracked community integrations.
+# Add specific entries here only for local-only experiments that should not be committed.
 examples/langgraph/
 tasks/
 skills/

CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing
+
+## Language
+
+All code, comments, documentation, and commit messages must be in **English**.
+
+## Commit Messages
+
+Use the format: `<type>: <short description>`
+
+Allowed types:
+
+| Type | When to use |
+|------|-------------|
+| `feat` | New feature or tool |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `chore` | Maintenance (deps, config, build) |
+| `refactor` | Code restructure, no behavior change |
+| `test` | Adding or updating tests |
+
+Examples:
+
+```
+feat: add ckan_group_search tool
+fix: handle timeout errors in datastore queries
+docs: update Docker setup instructions
+```
+
+Keep the subject line under 72 characters. No period at the end.
+
+## Project Structure
+
+```
+ckan-mcp-server/
+├── src/              # Source code (TypeScript)
+├── tests/            # Test suite
+├── docs/             # Documentation
+├── docker/           # Core Docker files (Dockerfile, compose, bridge)
+├── examples/         # Community integrations (one subfolder per integration)
+│   └── <name>/
+│       └── README.md
+├── openspec/         # Spec-driven change proposals
+└── scripts/          # Utility scripts
+```
+
+Place files in the right folder. Do not add new files to the repo root unless they are standard top-level files (README, LICENSE, Dockerfile, etc.).
+
+## Pull Requests
+
+Before opening a PR:
+
+- [ ] Branch from `main` and keep it up to date with upstream
+- [ ] No unrelated diffs (check `git diff main` carefully)
+- [ ] Do not modify `src/portals.json` unless the PR is specifically about portals — local fork customizations should stay in your fork
+- [ ] All tests pass: `npm test`
+- [ ] Build succeeds: `npm run build`
+
+## Adding an Example Integration
+
+Community integrations go under `examples/<name>/`. Each integration must have a `README.md` explaining what it does and how to run it. The core server files (`src/`, `docker/`) must not be modified as part of an example contribution.

docker/README.md

@@ -11,8 +11,7 @@ ckan-mcp-server/
 ├── Dockerfile               ← multi-stage build (builder + runtime)
 ├── docker-compose.yml       ← orchestration with variables and healthcheck
 ├── docker/
-│   ├── README.md            ← this file
-│   └── ckan-mcp-bridge.js   ← stdio bridge for Claude Desktop
+│   └── README.md            ← this file
 └── ... (rest of the repo)
 ```
 
@@ -55,25 +54,7 @@ docker run -d \
 
 ## Configuring Claude Desktop with the Container
 
-Once the container is running, add the following to `claude_desktop_config.json`.
-Set `MCP_URL` to point to your Docker host if running on a remote machine.
-
-```json
-{
-  "mcpServers": {
-    "ckan": {
-      "command": "node",
-      "args": ["/path/to/ckan-mcp-server/docker/ckan-mcp-bridge.js"],
-      "env": {
-        "MCP_URL": "http://localhost:3000/mcp"
-      }
-    }
-  },
-  "preferences": {
-    "coworkWebSearchEnabled": true
-  }
-}
-```
+Use the stdio bridge from [`examples/ollama-chat/`](../examples/ollama-chat/README.md) to connect Claude Desktop to the running container.
 
 ## Logs and Monitoring
 

examples/ollama-chat/README.md

@@ -0,0 +1,40 @@
+# Ollama Chat — stdio bridge for ckan-mcp-server
+
+This example provides a stdio bridge that allows MCP clients configured for local process communication (e.g. Claude Desktop) to talk to a `ckan-mcp-server` instance running as an HTTP container.
+
+```
+MCP client (stdio) <---> ckan-mcp-bridge.js <---> ckan-mcp-server (HTTP)
+```
+
+## Prerequisites
+
+- `ckan-mcp-server` running as a Docker container (see [`docker/README.md`](../../docker/README.md))
+- Node.js installed on the host machine
+
+## Usage
+
+### Claude Desktop
+
+Add this to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ckan": {
+      "command": "node",
+      "args": ["/path/to/ckan-mcp-server/examples/ollama-chat/ckan-mcp-bridge.js"],
+      "env": {
+        "MCP_URL": "http://localhost:3000/mcp"
+      }
+    }
+  }
+}
+```
+
+Set `MCP_URL` to point to your Docker host if the container runs on a remote machine.
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MCP_URL` | `http://localhost:3000/mcp` | URL of the running ckan-mcp-server |

docker/ckan-mcp-bridge.js examples/ollama-chat/ckan-mcp-bridge.jsdocker/ckan-mcp-bridge.js renamed to examples/ollama-chat/ckan-mcp-bridge.js

@@ -0,0 +1,19 @@
+# Change: Add CONTRIBUTING.md
+
+## Why
+
+External contributors (e.g. PR #14) repeatedly hit the same friction points: wrong language, wrong file placement, local fork diffs leaking in. A single reference document would cut review round-trips.
+
+## What Changes
+
+- Add `CONTRIBUTING.md` at repo root with:
+  - Language policy (English only)
+  - Commit message conventions (written inline, not linked)
+  - Project structure overview (where files belong)
+  - PR checklist (clean branch, no unrelated diffs)
+  - How to add examples (`examples/<name>/`)
+
+## Impact
+
+- Affected specs: contributor-guide (new)
+- Affected code: none (docs only)

openspec/changes/add-contributing-guide/proposal.md

@@ -0,0 +1,20 @@
+## ADDED Requirements
+
+### Requirement: Contribution Guide Document
+The project SHALL provide a `CONTRIBUTING.md` at the repo root that covers language policy, commit conventions, project structure, and PR checklist.
+
+#### Scenario: Language policy
+- **WHEN** a contributor opens the file
+- **THEN** they see that all code, comments, docs, and commit messages must be in English
+
+#### Scenario: Commit conventions
+- **WHEN** a contributor reads the commit section
+- **THEN** they see the format: `<type>: <short description>` with allowed types (feat, fix, docs, chore, refactor, test)
+
+#### Scenario: Project structure
+- **WHEN** a contributor reads the structure section
+- **THEN** they understand where files belong: src/ for code, docs/ for docs, examples/ for community integrations, docker/ for Docker core files
+
+#### Scenario: PR checklist
+- **WHEN** a contributor reads the PR section
+- **THEN** they see: branch from main, no unrelated diffs, no local-only files (e.g. portals.json changes), tests pass

openspec/changes/add-contributing-guide/specs/contributor-guide/spec.md

@@ -0,0 +1,3 @@
+## 1. Implementation
+- [x] 1.1 Write `CONTRIBUTING.md` at repo root
+- [x] 1.2 Verify language, commit, structure, and PR sections are all present

openspec/changes/add-contributing-guide/tasks.md

@@ -0,0 +1,18 @@
+# Change: Add examples/ structure
+
+## Why
+
+PR #14 introduced an Ollama+React integration but had no clear home. `docker/ckan-mcp-bridge.js` ended up in `docker/` even though it belongs to that integration, not to the core Docker setup. A formalized `examples/` pattern prevents this ambiguity for future contributors.
+
+## What Changes
+
+- Move `docker/ckan-mcp-bridge.js` → `examples/ollama-chat/ckan-mcp-bridge.js`
+- Add `examples/ollama-chat/README.md` documenting the integration
+- Update `docker/README.md` to remove reference to the bridge
+- Update root `.gitignore`: replace specific `examples/langgraph/` with a policy comment
+- Document the `examples/<name>/` pattern in `CONTRIBUTING.md` (companion to add-contributing-guide)
+
+## Impact
+
+- Affected specs: examples-structure (new)
+- Affected code: `docker/README.md`, `docker/ckan-mcp-bridge.js` (moved), `.gitignore`

openspec/changes/add-examples-structure/proposal.md

@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: Examples Folder Convention
+The project SHALL maintain an `examples/` folder for community integrations, where each integration lives in its own subdirectory with a README.
+
+#### Scenario: New integration placement
+- **WHEN** a contributor adds an integration (e.g. Ollama, LangGraph)
+- **THEN** it goes under `examples/<integration-name>/` with at minimum a `README.md`
+
+#### Scenario: Core Docker files unaffected
+- **WHEN** a contributor looks at `docker/`
+- **THEN** they find only files needed to run the MCP server itself (Dockerfile, docker-compose.yml, docker/README.md)
+
+### Requirement: Ollama Chat Example
+The project SHALL include `examples/ollama-chat/` with the stdio bridge and documentation for running the server via Ollama.
+
+#### Scenario: Bridge file location
+- **WHEN** a user needs the stdio bridge for Ollama
+- **THEN** they find it at `examples/ollama-chat/ckan-mcp-bridge.js`
+
+#### Scenario: README present
+- **WHEN** a user opens `examples/ollama-chat/`
+- **THEN** they find a README explaining how to use the bridge with Ollama