secubox-openwrt/DOCS/CODEX.md

# SecuBox Codex Field Manual

**Version:** 1.0.0  
**Last Updated:** 2025-12-28  
**Status:** Active

---

## Context & Scope

SecuBox bundles fifteen+ security and network dashboards for OpenWrt with a unified build/validation toolchain and CI that ships `.ipk`/`.apk` artifacts automatically (see `README.md` for the module catalogue and CI badges, `README.md:7-34`). The documentation set is intentionally layered—`DOCS/DOCUMENTATION-INDEX.md` routes newcomers, AI assistants, and maintainers to the right depth, so always start requests there before diving into large guides (`DOCS/DOCUMENTATION-INDEX.md:15-31`).

Use this file when you need to brief Codex (or any automation agent) quickly about SecuBox expectations: what standards are immutable, how to craft prompts, where to get help, which decisions shaped today’s tree, and what TODOs should stay in sight during automation runs.

### Module & Documentation Map
- `README.md`: one-page overview, compatibility matrix, and “what’s new” callouts (`README.md:7-34`).
- `DOCS/QUICK-START.md`: critical rules, design tokens, commands, and error playbooks (`DOCS/QUICK-START.md:9-195`).
- `DOCS/DEVELOPMENT-GUIDELINES.md`: deep dive into architecture, RPCD, ubus, CSS/JS conventions, and deployment (see summary in `DOCS/DOCUMENTATION-INDEX.md:68-82`).
- `DOCS/MODULE-IMPLEMENTATION-GUIDE.md` + `DOCS/FEATURE-REGENERATION-PROMPTS.md`: regeneration workflow plus ready-to-use prompts for all modules (`DOCS/DOCUMENTATION-INDEX.md:102-149`).
- `DOCS/CODE-TEMPLATES.md`: copy/paste-safe scaffolding for LuCI JS, RPCD scripts, and APIs (`DOCS/DOCUMENTATION-INDEX.md:153-159`).

---

## Best-Practice Snapshot

### Non-Negotiables (bake into every prompt or PR)
- RPCD filename **must** equal the ubus object (prevents `-32000 Object not found`, `DOCS/QUICK-START.md:11-18`).
- Menu JSON `path` **must** mirror the view path (avoids 404s, `DOCS/QUICK-START.md:20-26`).
- Permissions: RPCD 755, LuCI assets 644, otherwise RPCD won’t execute or LuCI returns 403 (`DOCS/QUICK-START.md:28-37`).
- Always run `./secubox-tools/validate-modules.sh` before opening PRs or tagging builds (reinforced in `README.md:18-23` and `DOCS/QUICK-START.md:122-134`).
- Keep design tokens consistent: dark palette (`#0a0a0f` base, `#6366f1→#8b5cf6` gradients), Inter + JetBrains Mono fonts, `.sh-*`/`.sb-*` components, and responsive grid widths defined in the quick start (`DOCS/QUICK-START.md:74-114`).

### Validation & Toolchain Flow
1. **Permissions Repair (local/remote):** `./secubox-tools/fix-permissions.sh --local|--remote` for automated chmod sanity (`DOCS/QUICK-START.md:55-66, 125-127`).
2. **Full Validation:** `./secubox-tools/validate-modules.sh` (runs seven structural checks including permission scan) (`DOCS/QUICK-START.md:122-134,185-189`).
3. **Module Builds:** `./secubox-tools/local-build.sh build <module>` for quick smoke tests or `make package/<module>/compile V=s` inside SDK (`DOCS/QUICK-START.md:135-143`).
4. **Deploy/Fix:** Copy to router via `scp`, normalize perms, flush `luci` caches, restart `rpcd`/`uhttpd` (`DOCS/QUICK-START.md:144-167`).
5. **Debug:** Validate ubus objects, inspect LuCI resources, and tail `logread` immediately after deployment (`DOCS/QUICK-START.md:156-167`).

### Design & UX Reminders
- Stats tiles minimum 130 px width, metrics 240 px, detail cards 300 px: encode these CSS grid rules to keep dashboards fluid on 720p+ viewports (`DOCS/QUICK-START.md:105-114`).
- Buttons, tabs, and cards expose `.sh-` utility classes; prefer gradient borders and neon states over inline styles for maintainability (same section).
- Align copy with README taxonomy (Core Control, Security & Monitoring, Network Intelligence, etc.) so documentation and UI stay in sync (`README.md:37-152` excerpt).

---

## Prompt Playbook

When drafting Codex/LLM prompts, supply enough structure so the assistant can reuse existing patterns instead of inventing them. Reuse this outline:

```text
Context:
- Target module + file(s) + desired change.
- Any relevant excerpts from CODE-TEMPLATES or existing JS/RPCD files.

Requirements:
- Restate non-negotiables (RPCD naming, menu path, permissions, design tokens).
- Mention validation commands Codex should run or assume.
- Call out API endpoints, ubus objects, or metrics to surface.

Deliverables:
- Files to touch (path + rationale).
- Expected tests/validations (e.g., run ./secubox-tools/validate-modules.sh).
- UX cues (colors, grid sizes, component classes) referencing QUICK-START.

Guardrails:
- Note TODO items or documentation standards (version headers, cross-links, etc.).
- Remind Codex where to log changes (README, module changelog, etc.).
```

Pair the template with module-specific prompts from `DOCS/FEATURE-REGENERATION-PROMPTS.md` and the workflow from `DOCS/MODULE-IMPLEMENTATION-GUIDE.md` (`DOCS/DOCUMENTATION-INDEX.md:102-149`). That combination lets Codex inherit existing layout structures, RPCD shells, and API modules without brittle guesswork.

---

## Help & Troubleshooting

- **Pre-deploy Sanity:** Run the overlay disk/permission SSH checks before copying files; they are scripted inside the quick start so you can paste directly into terminal sessions (`DOCS/QUICK-START.md:40-53`).
- **Common Error Fixes:** Keep the quick fixes near: HTTP 403 (chmod assets), “No space left” (purge `/tmp/*.ipk` and backups), ubus `-32000` (chmod 755 + ubus list). Automate via `secubox-tools` whenever possible (`DOCS/QUICK-START.md:55-70,171-180`).
- **Design Drift:** If CSS feels inconsistent, cross-check against the palette/fonts/components found in this manual and in the design section of the quick start (`DOCS/QUICK-START.md:74-114`).
- **Need Examples?:** Pull actual JS/RPCD snippets from `DOCS/CODE-TEMPLATES.md` or live modules under `luci-app-*` to keep generated code idiomatic (`DOCS/DOCUMENTATION-INDEX.md:153-159`).
- **Still Blocked?:** `DOCS/DEVELOPMENT-GUIDELINES.md` holds the long-form reasoning for every standard; cite relevant sections when escalating issues so maintainers see the source of truth quickly (`DOCS/DOCUMENTATION-INDEX.md:68-82`).

---

## History

- **2025-12-26 – Full Dev Guides Released:** README announces the arrival of the comprehensive dev guides set (README badge section, `README.md:7-16`).
- **2025-12-27 – Documentation Index v1.0.0:** Central index formalized the document map and AI workflow branches (`DOCS/DOCUMENTATION-INDEX.md:1-31`).
- **2025-12-28 – Documentation Improvement Plan:** `TODO-ANALYSE.md` generated to coordinate versioning, cross-links, and archival tasks (`TODO-ANALYSE.md:1-34,71-150`).
- **2025-12-28 – Codex Manual Drafted:** This CODEX field manual formalizes how automation agents should operate going forward.

---

## TODO Radar (keep Codex aligned)

1. **Standardize version headers & dates** – ensure every `.md` shows `Version/Last Updated/Status` with consistent `YYYY-MM-DD` formatting; DOCUMENTATION-INDEX must describe the policy once updates land (`TODO-ANALYSE.md:24-68`).
2. **Add “See Also” cross-links** – wire QUICK-START, PERMISSIONS-GUIDE, VALIDATION-GUIDE, and other quick refs back to their parent guides and vice-versa so AI/users don’t get orphaned instructions (`TODO-ANALYSE.md:71-116`).
3. **Archive historical docs** – create `docs/archive/`, move outdated references (COMPLETION_REPORT, MODULE-ENABLE-DISABLE-DESIGN, BUILD_ISSUES, etc.), and drop an archive README describing contents (`TODO-ANALYSE.md:120-153`).
4. **Future work (Monthly/Quarterly)** – new diagrams, TESTING/SECURITY/PERFORMANCE guides, automation for doc freshness, and i18n decisions are queued later in `TODO-ANALYSE.md`; mention them when prompts may impact scope or format downstream.

Codex should treat the TODOs above as guardrails: if a task touches documentation, prefer solutions that inch us toward these goals (e.g., add version headers while editing a doc, or cross-link when touching quick references).

---

## Quick Reference Checklist for Codex Runs

- [ ] Confirm the request references the right guide/template to minimize hallucinations (`DOCS/DOCUMENTATION-INDEX.md` paths).
- [ ] Copy/paste the non-negotiables + validation flow into the prompt.
- [ ] State which TODO radar items the change advances (or at least does not regress).
- [ ] Cite commands/scripts to run post-change.
- [ ] Capture findings in PR/commit descriptions referencing this CODEX manual when relevant.

Use this living manual as both a pre-flight briefing and a debrief log for automation work. Update it whenever the standards above evolve so every future Codex session starts with the correct mental model.
-												docs: Reorganize documentation structure and add architecture diagrams

Major documentation improvements and restructuring for better maintainability
and navigation.

## Structural Changes

### New Documentation Organization
- Move all documentation to DOCS/ directory for better organization
- Create DOCS/archive/ for historical documents
- Move deployment scripts to secubox-tools/ directory

### Archived Documents
- COMPLETION_REPORT.md → archive/ (project milestone)
- MODULE-ENABLE-DISABLE-DESIGN.md → archive/ (feature implemented)
- BUILD_ISSUES.md → archive/ (issues resolved)
- Add archive/README.md with archiving policy and document index

## Documentation Enhancements

### Version Standardization
- Add version headers to CLAUDE.md (v1.0.0)
- Add version headers to BUILD_ISSUES.md (v1.0.0)
- Standardize date format to YYYY-MM-DD across all docs

### Cross-References & Navigation
- Add "See Also" sections to PERMISSIONS-GUIDE.md
- Add "See Also" sections to VALIDATION-GUIDE.md
- Link quick references to detailed guides
- Improve documentation discoverability

### Architecture Diagrams (Mermaid)
Add 3 professional diagrams to DEVELOPMENT-GUIDELINES.md:

1. **System Architecture Diagram** (§2)
   - Complete data flow: Browser → LuCI → RPCD → ubus → System
   - Color-coded components by layer
   - Shows JavaScript, RPC, RPCD daemon, UCI, system services

2. **Deployment Workflow Diagram** (§9)
   - Step-by-step deployment process with validation checkpoints
   - Error recovery paths for common issues (403, 404, -32000)
   - Local validation, file transfer, permission fixes, service restarts

3. **Component Hierarchy Diagram** (§1)
   - Standard page structure and CSS class relationships
   - Page → Header → Stats → Content → Cards → Buttons
   - Shows design system component organization

## New Files

### TODO-ANALYSE.md
- Comprehensive documentation improvement roadmap
- Tasks categorized: Immediate, Short-term, Long-term, Optional
- Progress tracking with acceptance criteria
- Covers testing, security, performance guides
- Documentation automation plans

## Benefits

✅ Cleaner project structure (docs in DOCS/, tools in secubox-tools/)
✅ Better documentation navigation with cross-references
✅ Visual understanding through architecture diagrams
✅ Historical documents archived but accessible
✅ Standardized versioning across all documentation
✅ Clear roadmap for future documentation improvements

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

											
										
										
											2025-12-28 08:47:10 +00:00
+								# SecuBox Codex Field Manual
 								**Version:** 1.0.0
 								**Last Updated:** 2025-12-28
 								**Status:** Active
 								---
 								## Context & Scope
 								SecuBox bundles fifteen+ security and network dashboards for OpenWrt with a unified build/validation toolchain and CI that ships `.ipk`/`.apk` artifacts automatically (see `README.md` for the module catalogue and CI badges, `README.md:7-34`). The documentation set is intentionally layered—`DOCS/DOCUMENTATION-INDEX.md` routes newcomers, AI assistants, and maintainers to the right depth, so always start requests there before diving into large guides (`DOCS/DOCUMENTATION-INDEX.md:15-31`).
 								Use this file when you need to brief Codex (or any automation agent) quickly about SecuBox expectations: what standards are immutable, how to craft prompts, where to get help, which decisions shaped today’s tree, and what TODOs should stay in sight during automation runs.
 								### Module & Documentation Map
 								- `README.md`: one-page overview, compatibility matrix, and “what’s new” callouts (`README.md:7-34`).
 								- `DOCS/QUICK-START.md`: critical rules, design tokens, commands, and error playbooks (`DOCS/QUICK-START.md:9-195`).
 								- `DOCS/DEVELOPMENT-GUIDELINES.md`: deep dive into architecture, RPCD, ubus, CSS/JS conventions, and deployment (see summary in `DOCS/DOCUMENTATION-INDEX.md:68-82`).
 								- `DOCS/MODULE-IMPLEMENTATION-GUIDE.md` + `DOCS/FEATURE-REGENERATION-PROMPTS.md`: regeneration workflow plus ready-to-use prompts for all modules (`DOCS/DOCUMENTATION-INDEX.md:102-149`).
 								- `DOCS/CODE-TEMPLATES.md`: copy/paste-safe scaffolding for LuCI JS, RPCD scripts, and APIs (`DOCS/DOCUMENTATION-INDEX.md:153-159`).
 								---
 								## Best-Practice Snapshot
 								### Non-Negotiables (bake into every prompt or PR)
 								- RPCD filename **must** equal the ubus object (prevents `-32000 Object not found`, `DOCS/QUICK-START.md:11-18`).
 								- Menu JSON `path` **must** mirror the view path (avoids 404s, `DOCS/QUICK-START.md:20-26`).
 								- Permissions: RPCD 755, LuCI assets 644, otherwise RPCD won’t execute or LuCI returns 403 (`DOCS/QUICK-START.md:28-37`).
 								- Always run `./secubox-tools/validate-modules.sh` before opening PRs or tagging builds (reinforced in `README.md:18-23` and `DOCS/QUICK-START.md:122-134`).
 								- Keep design tokens consistent: dark palette (`#0a0a0f` base, `#6366f1→#8b5cf6` gradients), Inter + JetBrains Mono fonts, `.sh-*`/`.sb-*` components, and responsive grid widths defined in the quick start (`DOCS/QUICK-START.md:74-114`).
 								### Validation & Toolchain Flow
 . **Permissions Repair (local/remote):** `./secubox-tools/fix-permissions.sh --local|--remote` for automated chmod sanity (`DOCS/QUICK-START.md:55-66, 125-127`).
 . **Full Validation:** `./secubox-tools/validate-modules.sh` (runs seven structural checks including permission scan) (`DOCS/QUICK-START.md:122-134,185-189`).
 . **Module Builds:** `./secubox-tools/local-build.sh build <module>` for quick smoke tests or `make package/<module>/compile V=s` inside SDK (`DOCS/QUICK-START.md:135-143`).
 . **Deploy/Fix:** Copy to router via `scp`, normalize perms, flush `luci` caches, restart `rpcd`/`uhttpd` (`DOCS/QUICK-START.md:144-167`).
 . **Debug:** Validate ubus objects, inspect LuCI resources, and tail `logread` immediately after deployment (`DOCS/QUICK-START.md:156-167`).
 								### Design & UX Reminders
 								- Stats tiles minimum 130 px width, metrics 240 px, detail cards 300 px: encode these CSS grid rules to keep dashboards fluid on 720p+ viewports (`DOCS/QUICK-START.md:105-114`).
 								- Buttons, tabs, and cards expose `.sh-` utility classes; prefer gradient borders and neon states over inline styles for maintainability (same section).
 								- Align copy with README taxonomy (Core Control, Security & Monitoring, Network Intelligence, etc.) so documentation and UI stay in sync (`README.md:37-152` excerpt).
 								---
 								## Prompt Playbook
 								When drafting Codex/LLM prompts, supply enough structure so the assistant can reuse existing patterns instead of inventing them. Reuse this outline:
 								```text
 								Context:
 								- Target module + file(s) + desired change.
 								- Any relevant excerpts from CODE-TEMPLATES or existing JS/RPCD files.
 								Requirements:
 								- Restate non-negotiables (RPCD naming, menu path, permissions, design tokens).
 								- Mention validation commands Codex should run or assume.
 								- Call out API endpoints, ubus objects, or metrics to surface.
 								Deliverables:
 								- Files to touch (path + rationale).
 								- Expected tests/validations (e.g., run ./secubox-tools/validate-modules.sh).
 								- UX cues (colors, grid sizes, component classes) referencing QUICK-START.
 								Guardrails:
 								- Note TODO items or documentation standards (version headers, cross-links, etc.).
 								- Remind Codex where to log changes (README, module changelog, etc.).
 								```
 								Pair the template with module-specific prompts from `DOCS/FEATURE-REGENERATION-PROMPTS.md` and the workflow from `DOCS/MODULE-IMPLEMENTATION-GUIDE.md` (`DOCS/DOCUMENTATION-INDEX.md:102-149`). That combination lets Codex inherit existing layout structures, RPCD shells, and API modules without brittle guesswork.
 								---
 								## Help & Troubleshooting
 								- **Pre-deploy Sanity:** Run the overlay disk/permission SSH checks before copying files; they are scripted inside the quick start so you can paste directly into terminal sessions (`DOCS/QUICK-START.md:40-53`).
 								- **Common Error Fixes:** Keep the quick fixes near: HTTP 403 (chmod assets), “No space left” (purge `/tmp/*.ipk` and backups), ubus `-32000` (chmod 755 + ubus list). Automate via `secubox-tools` whenever possible (`DOCS/QUICK-START.md:55-70,171-180`).
 								- **Design Drift:** If CSS feels inconsistent, cross-check against the palette/fonts/components found in this manual and in the design section of the quick start (`DOCS/QUICK-START.md:74-114`).
 								- **Need Examples?:** Pull actual JS/RPCD snippets from `DOCS/CODE-TEMPLATES.md` or live modules under `luci-app-*` to keep generated code idiomatic (`DOCS/DOCUMENTATION-INDEX.md:153-159`).
 								- **Still Blocked?:** `DOCS/DEVELOPMENT-GUIDELINES.md` holds the long-form reasoning for every standard; cite relevant sections when escalating issues so maintainers see the source of truth quickly (`DOCS/DOCUMENTATION-INDEX.md:68-82`).
 								---
 								## History
 								- **2025-12-26 – Full Dev Guides Released:** README announces the arrival of the comprehensive dev guides set (README badge section, `README.md:7-16`).
 								- **2025-12-27 – Documentation Index v1.0.0:** Central index formalized the document map and AI workflow branches (`DOCS/DOCUMENTATION-INDEX.md:1-31`).
 								- **2025-12-28 – Documentation Improvement Plan:** `TODO-ANALYSE.md` generated to coordinate versioning, cross-links, and archival tasks (`TODO-ANALYSE.md:1-34,71-150`).
 								- **2025-12-28 – Codex Manual Drafted:** This CODEX field manual formalizes how automation agents should operate going forward.
 								---
 								## TODO Radar (keep Codex aligned)
 . **Standardize version headers & dates** – ensure every `.md` shows `Version/Last Updated/Status` with consistent `YYYY-MM-DD` formatting; DOCUMENTATION-INDEX must describe the policy once updates land (`TODO-ANALYSE.md:24-68`).
 . **Add “See Also” cross-links** – wire QUICK-START, PERMISSIONS-GUIDE, VALIDATION-GUIDE, and other quick refs back to their parent guides and vice-versa so AI/users don’t get orphaned instructions (`TODO-ANALYSE.md:71-116`).
 . **Archive historical docs** – create `docs/archive/`, move outdated references (COMPLETION_REPORT, MODULE-ENABLE-DISABLE-DESIGN, BUILD_ISSUES, etc.), and drop an archive README describing contents (`TODO-ANALYSE.md:120-153`).
 . **Future work (Monthly/Quarterly)** – new diagrams, TESTING/SECURITY/PERFORMANCE guides, automation for doc freshness, and i18n decisions are queued later in `TODO-ANALYSE.md`; mention them when prompts may impact scope or format downstream.
 								Codex should treat the TODOs above as guardrails: if a task touches documentation, prefer solutions that inch us toward these goals (e.g., add version headers while editing a doc, or cross-link when touching quick references).
 								---
 								## Quick Reference Checklist for Codex Runs
 								- [ ] Confirm the request references the right guide/template to minimize hallucinations (`DOCS/DOCUMENTATION-INDEX.md` paths).
 								- [ ] Copy/paste the non-negotiables + validation flow into the prompt.
 								- [ ] State which TODO radar items the change advances (or at least does not regress).
 								- [ ] Cite commands/scripts to run post-change.
 								- [ ] Capture findings in PR/commit descriptions referencing this CODEX manual when relevant.
 								Use this living manual as both a pre-flight briefing and a debrief log for automation work. Update it whenever the standards above evolve so every future Codex session starts with the correct mental model.