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:

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.