Skip to content

# 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.