Feature/document fixes

.github/workflows/docs.yml

@@ -0,0 +1,37 @@
+# SPDX-FileCopyrightText: 2026 AOT Technologies
+#
+# SPDX-License-Identifier: Apache-2.0
+
+name: docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install docs dependencies
+        run: pip install mkdocs mkdocs-material
+
+      - name: Build (PRs — validates site builds cleanly)
+        if: github.event_name == 'pull_request'
+        run: mkdocs build
+
+      - name: Deploy to GitHub Pages
+        if: github.event_name == 'push'
+        run: mkdocs gh-deploy --force

.gitignore

@@ -37,6 +37,9 @@ coverage.xml
 bandit-report.json
 .venv*/
 
+# MkDocs generated site
+/site/
+
 # debug
 launch.json
 

docs/architecture.md

@@ -1,6 +1,8 @@
-# SPDX-FileCopyrightText: 2026 AOT Technologies
-#
-# SPDX-License-Identifier: Apache-2.0
+<!--
+SPDX-FileCopyrightText: 2026 AOT Technologies
+
+SPDX-License-Identifier: Apache-2.0
+-->
 
 # Node Wire Architecture
 

docs/compliance/hipaa-considerations.md

@@ -1,6 +1,8 @@
-# SPDX-FileCopyrightText: 2026 AOT Technologies
-#
-# SPDX-License-Identifier: Apache-2.0
+<!--
+SPDX-FileCopyrightText: 2026 AOT Technologies
+
+SPDX-License-Identifier: Apache-2.0
+-->
 
 # HIPAA Compliance Considerations
 

docs/configuration.md

@@ -1,6 +1,8 @@
-# SPDX-FileCopyrightText: 2026 AOT Technologies
-#
-# SPDX-License-Identifier: Apache-2.0
+<!--
+SPDX-FileCopyrightText: 2026 AOT Technologies
+
+SPDX-License-Identifier: Apache-2.0
+-->
 
 # Configuration Guide
 

docs/contributing.md

@@ -0,0 +1,109 @@
+<!--
+SPDX-FileCopyrightText: 2026 AOT Technologies
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Contributing to Node Wire
+
+Thanks for your interest in contributing! This guide covers how to set up a
+development environment, the quality checks we enforce, and the conventions for
+submitting changes. By contributing you agree that your contributions are
+licensed under the project's [Apache License 2.0](https://github.com/AOT-Technologies/node-wire/blob/main/LICENSE) and that you sign off
+each commit under the
+[Developer Certificate of Origin](#developer-certificate-of-origin-dco).
+
+## Prerequisites
+
+| Requirement | Version | Notes |
+|---|---|---|
+| Python | 3.11+ | Required to run the platform |
+| `uv` | Latest | Recommended for dependency management and reproducible installs |
+| Git | Any recent version | |
+| Docker | Latest | Only needed for MCP server image builds |
+
+## Development Setup
+
+Install the project and all development dependencies from the committed
+lockfile:
+
+```bash
+git clone https://github.com/AOT-Technologies/node-wire.git
+cd node-wire
+uv sync --frozen --all-extras --dev
+```
+
+Install the pre-commit hooks so checks run automatically before each commit:
+
+```bash
+pre-commit install
+```
+
+## Quality Checks
+
+All of the following run in CI on pull requests against `main`. Run them
+locally before opening a PR:
+
+- **Lint:** `uv run ruff check .`
+- **Auto-fix & format:** `uv run ruff check --fix . && uv run ruff format .`
+- **Type-check:** `uv run mypy`
+- **Security (SAST):** `uv run bandit -c pyproject.toml -r src`
+- **Tests:** `uv run pytest`
+
+See [Code Quality](code-quality-compliance.md) and [Quality & Security Gates](quality-security-gates.md) for the full tooling reference.
+
+## Licensing & REUSE Compliance
+
+This project is [REUSE](https://reuse.software/) compliant. **Every new file
+must carry an SPDX header.** For source and Markdown files use the project's
+standard header, e.g. for Python:
+
+```python
+# SPDX-FileCopyrightText: 2026 AOT Technologies
+#
+# SPDX-License-Identifier: Apache-2.0
+```
+
+and for Markdown/HTML, an HTML comment with the same two SPDX tags.
+
+## Git Identity
+
+Configure your git identity before committing. Commits must use your real
+name and a valid email so attribution is accurate:
+
+```bash
+git config user.name "Your Name"
+git config user.email "you@example.com"
+```
+
+## Developer Certificate of Origin (DCO)
+
+This project uses the [Developer Certificate of Origin](https://developercertificate.org/)
+(DCO) instead of a CLA. Add a `Signed-off-by` trailer to **every commit**:
+
+```bash
+git commit -s -m "Your commit message"
+```
+
+CI (`.github/workflows/dco.yml`) verifies that every commit in a pull request
+carries a sign-off matching its author. If you forget:
+
+```bash
+git rebase --signoff main
+git push --force-with-lease
+```
+
+## Submitting Changes
+
+1. Fork the repository and create a feature branch from `main`.
+2. Make your change, including tests and documentation updates where relevant.
+   Sign off every commit with `git commit -s`.
+3. Ensure all quality checks above pass locally.
+4. Open a pull request against `main` with a clear description and motivation.
+5. A maintainer will review your PR. Address feedback by pushing additional
+   commits to your branch.
+
+## Reporting Bugs & Requesting Features
+
+Use the GitHub issue templates. For **security vulnerabilities**, do not open a
+public issue — follow the [Security Policy](https://github.com/AOT-Technologies/node-wire/blob/main/SECURITY.md) instead.

docs/index.md

@@ -0,0 +1,73 @@
+<!--
+SPDX-FileCopyrightText: 2026 AOT Technologies
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Node Wire
+
+[![CI](https://github.com/AOT-Technologies/node-wire/actions/workflows/pytest.yml/badge.svg)](https://github.com/AOT-Technologies/node-wire/actions/workflows/pytest.yml)
+[![CodeQL](https://github.com/AOT-Technologies/node-wire/actions/workflows/codeql.yml/badge.svg)](https://github.com/AOT-Technologies/node-wire/actions/workflows/codeql.yml)
+[![PyPI](https://img.shields.io/pypi/v/node-wire.svg)](https://pypi.org/project/node-wire/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/AOT-Technologies/node-wire/blob/main/LICENSE)
+
+Node Wire is a three-layer Python platform that runs connector adapters (Google Drive, SMTP, Stripe, FHIR, Salesforce, Slack, and more) and exposes them over REST, gRPC, or MCP. It provides a consistent execution contract with built-in validation, resilience, and telemetry.
+
+## Quick Start
+
+```bash
+git clone https://github.com/AOT-Technologies/node-wire.git
+cd node-wire
+uv sync --frozen --all-extras --dev
+cp sample.env .env
+MODE=API uv run node-wire
+```
+
+Open [http://localhost:8000/docs](http://localhost:8000/docs) for the Swagger UI.
+
+## Key Sections
+
+<div class="grid cards" markdown>
+
+-   **Getting Started**
+
+    Set up your environment and configure connectors.
+
+    [:octicons-arrow-right-24: Installation](installation.md)
+
+-   **Architecture**
+
+    Understand the three-layer design: Runtime, Connectors, and Bindings.
+
+    [:octicons-arrow-right-24: Architecture](architecture.md)
+
+-   **Connectors**
+
+    Build or configure integrations with Google Drive, Salesforce, Slack, and more.
+
+    [:octicons-arrow-right-24: Connectors Guide](connectors.md)
+
+-   **MCP Integration**
+
+    Deploy connectors as Model Context Protocol servers for AI agents.
+
+    [:octicons-arrow-right-24: MCP Overview](mcp.md)
+
+</div>
+
+## Available Connectors
+
+| Connector | Protocol | Doc |
+|---|---|---|
+| Google Drive | REST + OAuth | [Guide](google_drive_connector.md) |
+| Salesforce | REST | [Guide](salesforce_connector.md) |
+| Slack | Events API | [Guide](slack_connector.md) |
+| SMTP | Email | [Connectors](connectors.md) |
+| Stripe | REST | [Connectors](connectors.md) |
+| FHIR Epic | SMART on FHIR | [Connectors](connectors.md) |
+| FHIR Cerner | SMART on FHIR | [Connectors](connectors.md) |
+| HTTP Generic | REST bridge | [Connectors](connectors.md) |
+
+## Contributing
+
+Contributions are welcome. See the [Contributing guide](contributing.md) for development setup, quality checks, and DCO requirements.

docs/installation.md

@@ -1,6 +1,8 @@
-# SPDX-FileCopyrightText: 2026 AOT Technologies
-#
-# SPDX-License-Identifier: Apache-2.0
+<!--
+SPDX-FileCopyrightText: 2026 AOT Technologies
+
+SPDX-License-Identifier: Apache-2.0
+-->
 
 # Installation Guide
 

docs/local-packages-to-images.md

@@ -14,7 +14,7 @@ The Dockerfiles in this repo install local wheel artifacts from `packages/**/dis
 
 ## Prerequisites
 
-- Python 3.12 available in your shell
+- Python 3.11+ available in your shell
 - Docker installed and running
 - Build tooling installed:
 
@@ -101,7 +101,7 @@ docker build -f docker/smtp/Dockerfile -t nw-smtp:local .
 
 ## Wheel requirements by image
 
-Each Dockerfile expects specific wheel files to exist in `dist/`:
+Each Dockerfile expects specific wheel files to exist in `dist/`. Keep this table in sync with the Dockerfiles in `docker/` — add a row here whenever you add a Tier 3 standalone MCP image (see [connectors.md — Step 12](connectors.md#adding-a-new-connector-checklist)).
 
 | Image | Required wheels |
 |---|---|