docs: Comprehensive README rewrite with enhanced structure and clarity

[fentz26]

User description

Major improvements:

• Updated badges and repository URLs to Neona-AI organization
• Rewrote introduction with clearer value proposition
• Added comprehensive Key Features section
• Enhanced architecture diagram with dual UI layers (CLI + TUI)
• Added Use Cases section explaining practical applications
• Clarified "What Neona Is" vs "What Neona Is NOT"
• Expanded TUI documentation with Textual features
• Enhanced API reference with parameter details
• Added comprehensive Security & Safety section with policy examples
• Updated project structure to include neona-tui Python package
• Expanded Configuration section with environment variables
• Rewrote Development section with testing, debugging tips
• Added Contributing guidelines and PR process
• Added Roadmap section (v0.0.1 status + upcoming features)
• Enhanced License section with AGPL-3.0 explanation
• Added Support & Community links section

The README now provides a complete picture of Neona's capabilities,
architecture, and development practices for both users and contributors.

---

PR Type

Documentation

---

Description

• Updated repository URLs and badges to Neona-AI organization

• Added comprehensive Key Features section highlighting core capabilities

• Enhanced architecture diagram with dual UI layers (CLI + TUI) and detailed component responsibilities

• Added Use Cases section explaining practical applications for multi-agent development

• Clarified "What Neona Is" vs "What Neona Is NOT" with specific examples

• Expanded TUI documentation with Textual features, keyboard controls, and command reference

• Added comprehensive HTTP API reference with endpoint tables and parameter details

• Added Security & Safety section covering command allowlisting, policy enforcement, and audit trails

• Updated project structure documentation to include neona-tui Python package

• Expanded Configuration section with environment variables and daemon settings

• Rewrote Development section with prerequisites, build instructions, testing, debugging tips, and project standards

• Added Contributing guidelines with ways to contribute and PR process

• Added Roadmap section with v0.0.1 status and upcoming features

• Enhanced License section with AGPL-3.0 explanation and enterprise/cloud information

• Added Support & Community links section with GitHub resources

---

Diagram Walkthrough

flowchart LR
  A["README Structure"] --> B["Introduction & Features"]
  A --> C["Architecture & Components"]
  A --> D["API & Configuration"]
  A --> E["Development & Contributing"]
  B --> B1["Key Features List"]
  B --> B2["Use Cases"]
  B --> B3["What Is/Is NOT"]
  C --> C1["Dual UI Layers Diagram"]
  C --> C2["Component Responsibilities"]
  D --> D1["HTTP API Reference"]
  D --> D2["Security & Safety"]
  D --> D3["Configuration Details"]
  E --> E1["Development Setup"]
  E --> E2["Testing & Debugging"]
  E --> E3["Contributing Guidelines"]
  E --> E4["Roadmap"]

Loading

File Walkthrough

Relevant files

Documentation

README.md Complete README restructure with enhanced documentation    README.md Updated all repository URLs from fentz26 to Neona-AI organization Rewrote introduction with clearer value proposition and tagline Added comprehensive Key Features section with 9 major capabilities Enhanced architecture diagram with dual UI layers (CLI + TUI) and detailed component breakdown Added Use Cases section with 5 practical application scenarios Expanded "What Neona Is" and "What Neona Is NOT" sections with specific examples Added detailed TUI documentation with Textual features, keyboard controls, and command reference table Added comprehensive HTTP API reference with endpoint tables for Tasks, Memory, and System endpoints Added Security & Safety section covering command allowlisting, policy enforcement, and PDR audit trails Updated project structure documentation to include neona-tui Python package and .ai directory details Expanded Configuration section with database location, daemon settings, and TUI discovery Rewrote Development section with prerequisites, build instructions, testing procedures, debugging tips, and project standards Added Contributing section with ways to contribute and pull request process Added Roadmap section with current version status and upcoming features Enhanced License section with AGPL-3.0 explanation and enterprise/cloud information Added Support & Community section with GitHub resources and contact information +466/-91

---

Note

Major README overhaul to document Neona comprehensively for users and contributors.

• Updates badges/links to Neona-AI/Neona and adds Go version badge
• Rewrites intro and adds Key Features, Use Cases, and clear ✅/❌ “What Neona Is/Is NOT”
• Expands Architecture with dual UI (CLI + TUI), component responsibilities, and ASCII diagram
• Adds detailed TUI docs (features, keyboard controls, command reference)
• Introduces full HTTP API reference with endpoints, params, and system routes
• Adds Security & Safety (command allowlisting, .ai/policy.yaml examples, PDR audit trail)
• Updates Project Structure (including neona-tui), Configuration (env vars/paths), and Development (build, test, debug)
• Adds Contributing guidelines, Roadmap (v0.0.1), License details, and Support & Community links

^{Written by Cursor Bugbot for commit 2642b4d. This will update automatically on new commits. Configure here.}

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Audit trail claims: The README asserts comprehensive PDR audit logging (including who/when/exit codes) but no implementation changes are shown to verify the logs include required context for all critical actions. Referred Code ### Audit Trail (PDR) Every operation is logged in Process Data Record (PDR) format: - Who claimed/executed the task - What commands were run - When each action occurred - Results and exit codes PDR logs are stored in SQLite and can be exported for compliance audits. Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Logging sensitivity: The README describes extensive PDR logging but does not demonstrate that logged fields avoid sensitive data (e.g., secrets in command args/output) or that logs are structured as required. Referred Code - **Audit Trails** - Comprehensive PDR (Process Data Record) logging for compliance and debugging - **Memory System** - Contextual knowledge base that persists across tasks and sessions - **Beautiful TUI** - Rich terminal interface built with Textual (Python) for interactive task management - **Secure by Default** - Command allowlisting, no secret access, minimal privilege execution - **Auto-Updates** - Automatic version checking and self-updating capabilities - **SQLite Backend** - Lightweight, serverless persistence with no external dependencies - **HTTP API** - RESTful API for programmatic access and custom integrations Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: API security claims: The README documents HTTP endpoints accepting inputs (e.g., command, args[], holder_id) and states local-only access, but no code changes are shown to confirm validation/sanitization and authorization controls align with the described security posture. Referred Code ## 🔌 HTTP API Reference The daemon exposes a RESTful API on `127.0.0.1:7466` by default. ### Task Endpoints | Endpoint | Method | Description | Parameters | |----------|--------|-------------|------------| | `/tasks` | POST | Create a new task | `title`, `description` | | `/tasks` | GET | List all tasks | `?status=pending\|claimed\|running\|completed\|failed` | | `/tasks/{id}` | GET | Get task details | - | | `/tasks/{id}/claim` | POST | Claim task with lease | `holder_id`, `ttl_sec` (default: 300) | | `/tasks/{id}/release` | POST | Release task lease | `holder_id` | | `/tasks/{id}/run` | POST | Execute command on task | `holder_id`, `command`, `args[]` | | `/tasks/{id}/logs` | GET | Get execution logs | - | | `/tasks/{id}/memory` | GET | Get task-specific memory | - | ### Memory Endpoints | Endpoint | Method | Description | Parameters | |----------|--------|-------------|------------| ... (clipped 14 lines) Learn more about managing compliance generic rules or creating your own custom rules
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	Add virtual environment setup instructions Add instructions to create and activate a Python virtual environment before installing dependencies for TUI development. README.md [418-431] ### Python TUI Development ```bash cd neona-tui + +# Create and activate a virtual environment +python3 -m venv .venv +source .venv/bin/activate # Install in development mode pip install -e ".[dev]" # Run with live reload textual run --dev neona_tui/app.py # Ensure daemon is running first # In another terminal: go run ./cmd/neona daemon - [ ] **Apply / Chat** <!-- /improve --apply_suggestion=0 --> <details><summary>Suggestion importance[1-10]: 6</summary> __ Why: The suggestion correctly identifies a missing best practice in the Python development instructions, and adding virtual environment steps will improve the developer setup experience and prevent potential dependency issues. </details></details></td><td align=center>Low </td></tr><tr><td> <details><summary>✅ <s>Correct and clarify TUI fallback path</s></summary> ___ <details><summary><b>Suggestion Impact:</b></summary>Updated the README's TUI fallback bullet to state "(when run from repo root)" and removed the leading "./" from the path, matching the suggested clarification. code diff: ```diff @@ -369,7 +369,7 @@ The Go CLI discovers the Python TUI using: 1. `NEONA_TUI_PATH` environment variable 2. `neona-tui` in system PATH -3. Development fallback: `./neona-tui/neona_tui/app.py` +3. Development fallback (when run from repo root): `neona-tui/neona_tui/app.py` Clarify that the TUI development fallback path assumes the command is run from the repository root. README.md [367-372] ### TUI Configuration The Go CLI discovers the Python TUI using: 1. `NEONA_TUI_PATH` environment variable 2. `neona-tui` in system PATH -3. Development fallback: `./neona-tui/neona_tui/app.py` +3. Development fallback (when run from repo root): `neona-tui/neona_tui/app.py` [Suggestion processed] Suggestion importance[1-10]: 4 __ Why: The suggestion correctly identifies that the documented fallback path is fragile, and the proposed clarification improves the documentation's accuracy for developers.	Low
	Update