docs: improve onboarding, architecture documentation, and contribution guidance

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,28 +1,62 @@
-<!-- Thanks for contributing to NEST! Please fill out the sections below. -->
+<!-- Thank you for contributing to NEST! Please complete the sections below to help reviewers understand and evaluate your changes efficiently. -->
+
+# Pull Request Summary
 
 ## What does this PR do?
 
-<!-- A clear, concise description of the change and the motivation behind it. -->
+<!-- Provide a concise summary of the changes introduced in this pull request and the problem it solves or improvement it delivers. -->
+
+## Why is this change needed?
+
+<!-- Describe the motivation behind this change. Include any context, limitations, or user impact if relevant. -->
+
+## Type of Change
+
+Select all that apply:
+
+* [ ] 🐛 Bug Fix
+* [ ] ✨ New Feature
+* [ ] 📚 Documentation Improvement
+* [ ] 🧹 Refactor / Maintenance
+* [ ] 🚀 Infrastructure / Deployment (Docker, Compose, Nginx)
+* [ ] ⚡ Performance Improvement
+* [ ] 🔒 Security Enhancement
+
+## Related Issues
+
+<!-- Example: Closes #123, Fixes #456, Related to #789 -->
+
+## Testing
+
+Describe how the changes were tested.
+
+### Environment
+
+<!-- Example:
+- OS: Ubuntu 24.04
+- Docker: 28.x
+- Docker Compose: 2.x
+-->
 
-## Type of change
+### Validation Steps
 
-- [ ] 🐛 Bug fix
-- [ ] ✨ New feature
-- [ ] 📚 Documentation
-- [ ] 🧹 Refactor / chore
-- [ ] 🚀 Deployment / infra (Docker, compose, nginx)
+<!-- List commands executed, screenshots captured, or manual verification steps reviewers can follow. -->
 
-## Related issues
+## Screenshots (if applicable)
 
-<!-- e.g. Closes #123 -->
+<!-- Include screenshots, terminal output, or recordings for UI or documentation changes. -->
 
-## How was this tested?
+## Reviewer Notes
 
-<!-- Commands run, environment, screenshots, or steps a reviewer can follow. -->
+<!-- Any specific areas where you'd like feedback or additional attention from reviewers. -->
 
 ## Checklist
 
-- [ ] I read the [Contributing Guide](../CONTRIBUTING.md)
-- [ ] I agree to the [Contributor License Agreement](../CONTRIBUTOR_LICENSE_AGREEMENT.md)
-- [ ] Docs updated if behavior or configuration changed
-- [ ] No secrets, tokens, or customer data included in the diff
+* [ ] I have read the Contributing Guide.
+* [ ] I agree to the Contributor License Agreement (CLA).
+* [ ] My changes are limited in scope and focused on a single improvement.
+* [ ] Documentation has been updated where necessary.
+* [ ] Configuration changes are clearly documented.
+* [ ] No secrets, API keys, tokens, or sensitive data are included.
+* [ ] Relevant testing has been completed successfully.
+* [ ] Existing functionality remains unaffected by these changes.

QUICKSTART.md

@@ -103,6 +103,8 @@ export NEST_API_URL="http://localhost"
 
 > **Where's your token?** `setup.sh` saved it in `.env`. Run: `grep CLI_API_TOKEN .env` to see it.
 
+The token is automatically generated during setup and stored in the `.env` file.
+
 **Option B: Interactive login (saves credentials permanently)**
 
 ```bash
@@ -150,10 +152,7 @@ The terminal will show the session connecting and streaming. **Don't close this
 
 ## Step 5 — Your AHA Moment 🎯
 
-Switch to your browser (or phone) and open:
-
-```
-http://localhost
+Switch to your browser and open the URL displayed by setup.sh. If accessing NEST from another device on your network, use the server's IP address instead of localhost.
 ```
 
 **You should now see the live session in the dashboard.**
@@ -238,14 +237,22 @@ You now have:
 | Problem | Fix |
 |---------|-----|
 | `annie` not found after install | Run `npm install -g @contextzero/nest` again; check your `$PATH` |
-| Web app shows blank / won't load | Wait 30s for DB init; run `docker compose logs nest-server` |
+| Web app is blank or fails to load | Wait 30s for DB init; run `docker compose logs nest-server` |
 | `401 Unauthorized` in CLI | Token mismatch — `setup.sh` generates it automatically. Run `grep CLI_API_TOKEN .env` to see your token. |
 | Port 80 already in use | Set `WEB_PORT=8080` in `.env`, then `docker compose restart` |
 | Session not appearing in dashboard | Confirm `NEST_API_URL` in CLI points to the correct server address |
 | Something else is wrong | Run `annie diagnose` — it prints a full diagnostic report |
 
 ---
 
+## Common First-Time Mistakes
+
+- Using an outdated Node.js version (requires v18+).
+- Forgetting to start Docker before running `setup.sh`.
+- Using `localhost` from a different device on the network.
+- Copying an incorrect `CLI_API_TOKEN`.
+- Forgetting to run `annie auth login` before starting an agent session.
+
 > **You're running an enterprise-grade AI workforce hub. For free. On your own infrastructure.**
 > 
 > When you're ready to take it further — HTTPS, multiple teams, custom LLM routing — everything is in [docs/DEVOPS.md](docs/DEVOPS.md) and [docs/CLI-BUSINESS.md](docs/CLI-BUSINESS.md).

README.md

@@ -14,7 +14,22 @@
   <a href="https://t.me/ctx0_io"><img src="https://img.shields.io/badge/Telegram-Join-26A5E4?style=flat-square&logo=telegram" alt="Telegram"></a>
 </p>
 
-NEST is a self-hosted AI workforce hub that consolidates fragmented tool stacks into a single, governed plane: organizational memory, multi-agent orchestration, 700+ models via BYOK, and full audit trails — all running on infrastructure you own. Built by Context Zero (CTX0) under a fair-code license, NEST gives enterprises the speed of modern AI tooling without surrendering data, cost control, or operational sovereignty.
+## What is NEST?
+
+NEST is a self-hosted AI workforce hub designed to help organizations deploy and manage AI securely on their own infrastructure.
+
+### Key Features
+
+- **Unified AI Platform** – Consolidates fragmented AI tools and workflows into a single, centralized workspace.
+- **Organizational Memory** – Enables teams to store, retrieve, and leverage institutional knowledge efficiently.
+- **Multi-Agent Orchestration** – Supports collaboration between multiple AI agents to automate complex tasks and workflows.
+- **Extensive Model Access** – Connects to **700+ AI models** through a Bring Your Own Key (BYOK) approach, providing flexibility and choice.
+- **Comprehensive Audit Trails** – Maintains detailed activity logs to ensure transparency, governance, and compliance.
+- **Self-Hosted & Secure** – Runs entirely on infrastructure owned and controlled by the organization, enhancing data privacy and security.
+- **Cost & Operational Control** – Eliminates dependency on third-party AI platforms, giving organizations greater control over expenses and operations.
+- **Enterprise-Ready** – Delivers the capabilities of modern AI tooling while preserving data sovereignty and governance requirements.
+
+Developed by **Context Zero (CTX0)** under a fair-code license, NEST empowers organizations to adopt AI without compromising security, compliance, or operational independence.
 
 > ⭐ **If NEST is useful to your team, star the repo** — it helps other organizations find a self-hosted, audited alternative to SaaS AI sprawl. See **[everything we've shipped →](https://github.com/contextzero/nest_hub/issues/17)** — live, dated, and independently verifiable.
 
@@ -61,44 +76,127 @@ NEST is organized as a set of composable modules sharing one audit and governanc
 | **Cost model** | ✅ Your keys, no per-seat platform fee | ❌ Per-seat + markup | ✅ Infra only |
 | **Lock-in** | ✅ Fair-code, source-available | ❌ Proprietary | ✅ None |
 
+Here's a cleaner and more professional version:
+
 ## Architecture
 
-Everything runs on infrastructure you own. Employee machines and browsers connect **outbound** to your hub; model providers are reached with **your** keys. No inbound access for anyone else.
+NEST is designed to run entirely on infrastructure you control, whether in the cloud, on-premises, or within air-gapped environments. Employee devices connect securely to the hub using outbound connections only, while AI model providers are accessed through your organization's own API keys (BYOK). This architecture ensures data sovereignty, security, and operational control without requiring inbound access from external parties.
+
+### Architecture Overview
+
+* **Employee Access** – Users interact with NEST through the Annie CLI or the web-based PWA from any browser.
+* **Outbound-Only Connectivity** – All client connections are outbound, minimizing exposure and simplifying network security.
+* **Self-Hosted Deployment** – NEST runs entirely on infrastructure owned and managed by your organization.
+* **High-Performance Backend** – Powered by a Rust-based server built with Axum, Socket.IO, and Server-Sent Events (SSE) for scalable real-time communication.
+* **Persistent Audit Logging** – PostgreSQL stores organizational data and maintains comprehensive audit trails for governance and compliance.
+* **Flexible Model Integration** – Connect to 700+ AI models through a Bring Your Own Key (BYOK) approach using providers such as OpenRouter, Fal, and direct model integrations.
 
 ```mermaid
 flowchart LR
-    CLI["Employees — annie CLI"] -->|outbound| NG
-    PWA["Web PWA — any browser"] -->|outbound| NG
-    subgraph infra["Your infrastructure: cloud, on-prem, air-gapped"]
-        NG["nginx"] --> SRV["NEST Server — Rust, Axum, Socket.IO, SSE"]
-        SRV --> DB[("PostgreSQL — full audit log")]
+    CLI["Employees - Annie CLI"] -->|Outbound Connection| NG
+    PWA["Web PWA - Any Browser"] -->|Outbound Connection| NG
+
+    subgraph INFRA["Your Infrastructure (Cloud, On-Premises, or Air-Gapped)"]
+        NG["Nginx Reverse Proxy"] --> SRV["NEST Server (Rust, Axum, Socket.IO, SSE)"]
+        SRV --> DB[("PostgreSQL<br/>Audit Logs & Data Storage")]
     end
-    SRV -->|BYOK| LLM["700+ models — OpenRouter, Fal, direct"]
+
+    SRV -->|BYOK| LLM["700+ AI Models<br/>OpenRouter, Fal, Direct Integrations"]
 ```
 
+This version explains *why* the architecture matters, not just *what* the components are, which is usually more valuable in documentation.
+
+
 Architecture: hexagonal (`domain` → `ports` → `application` → `adapters`). See the [security model](docs/SECURITY-MODEL.md) for the data-residency and audit posture.
 
+## Why Self-Hosting?
+
+NEST is designed for organizations that require full control over their AI infrastructure.
+
+### Benefits
+
+- Data remains within your infrastructure.
+- No vendor lock-in for AI models.
+- Flexible deployment across cloud, on-premises, or air-gapped environments.
+- Complete visibility through audit logging and governance controls.
+- Better cost management through BYOK model integrations.
+
 ## Quick Start
 
-Deploy the self-hosted hub with [Docker](https://docs.docker.com/get-docker/). Clone the repo and run the setup script — it generates secrets, pulls the published images, starts the stack, and waits for health:
+Deploy NEST on your own infrastructure using Docker. The setup script automatically generates the required secrets, downloads the latest published images, starts all services, and performs health checks to ensure the deployment is successful.
 
-```
+### Prerequisites
+
+Before starting, ensure the following tools are installed:
+
+* Docker
+* Docker Compose
+* Git
+
+### Installation
+
+```bash
 git clone https://github.com/contextzero/nest_hub.git
 cd nest_hub
 ./setup.sh
 ```
 
-Then open the PWA at `http://localhost` (or the `WEB_PORT` you set in `.env`) and install it on your phone, tablet, or desktop.
+### Accessing NEST
+
+Once deployment is complete, open the Progressive Web App (PWA) in your browser:
+
+```text
+http://localhost
+```
+
+If you have configured a custom `WEB_PORT` in your `.env` file, use that port instead.
+
+The PWA can be installed on desktop, tablet, and mobile devices for a native-app-like experience.
+
+### Day-2 Operations
+
+Common operational commands:
+
+```bash
+docker compose up -d                          # Start services
+docker compose down                           # Stop services
+docker compose logs -f                        # Stream logs
+docker compose pull && docker compose up -d   # Update to the latest images
+```
+
+## Troubleshooting
+
+### Docker is not running
+
+If you encounter Docker connection errors during setup, ensure that Docker is installed and running before executing:
+
+```bash
+./setup.sh
+```
+
+### Port already in use
+
+If `localhost` is unavailable after deployment, verify that the configured port is not being used by another application. You can also modify the `WEB_PORT` value in your `.env` file.
 
-Day-2 operations:
+### Services fail to start
 
+Check container status and logs:
+
+```bash
+docker compose ps
+docker compose logs -f
 ```
-docker compose up -d                          # start
-docker compose down                           # stop
-docker compose logs -f                        # stream logs
-docker compose pull && docker compose up -d   # update to the latest images
+
+### Updating NEST
+
+To update to the latest published images:
+
+```bash
+docker compose pull
+docker compose up -d
 ```
 
+
 ### CLI for developer machines
 
 Connect each workstation to your hub with the published CLI (package `@contextzero/nest`, binary `annie`):