<inputclass="md-option"data-md-color-media="(prefers-color-scheme: light)"data-md-color-scheme="default"data-md-color-primary="indigo"data-md-color-accent="purple"aria-label="Switch to dark mode"type="radio"name="__palette"id="__palette_0">
<labelclass="md-header__button md-icon"title="Switch to dark mode"for="__palette_1"hidden>
<inputclass="md-option"data-md-color-media="(prefers-color-scheme: dark)"data-md-color-scheme="slate"data-md-color-primary="indigo"data-md-color-accent="purple"aria-label="Switch to light mode"type="radio"name="__palette"id="__palette_1">
<labelclass="md-header__button md-icon"title="Switch to light mode"for="__palette_0"hidden>
<h1id="secubox-codex-field-manual">SecuBox Codex Field Manual<aclass="headerlink"href="#secubox-codex-field-manual"title="Permanent link">¶</a></h1>
<p><strong>Version:</strong> 1.0.0<br/>
<strong>Last Updated:</strong> 2025-12-28<br/>
<strong>Status:</strong> Active</p>
<hr/>
<h2id="context-scope">Context & Scope<aclass="headerlink"href="#context-scope"title="Permanent link">¶</a></h2>
<p>SecuBox bundles fifteen+ security and network dashboards for OpenWrt with a unified build/validation toolchain and CI that ships <code>.ipk</code>/<code>.apk</code> artifacts automatically (see <code>README.md</code> for the module catalogue and CI badges, <code>README.md:7-34</code>). The documentation set is intentionally layered—<code>DOCS/DOCUMENTATION-INDEX.md</code> routes newcomers, AI assistants, and maintainers to the right depth, so always start requests there before diving into large guides (<code>DOCS/DOCUMENTATION-INDEX.md:15-31</code>).</p>
<p>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.</p>
<h3id="module-documentation-map">Module & Documentation Map<aclass="headerlink"href="#module-documentation-map"title="Permanent link">¶</a></h3>
<ul>
<li><code>README.md</code>: one-page overview, compatibility matrix, and “what’s new” callouts (<code>README.md:7-34</code>).</li>
<li><code>DOCS/QUICK-START.md</code>: critical rules, design tokens, commands, and error playbooks (<code>DOCS/QUICK-START.md:9-195</code>).</li>
<li><code>DOCS/DEVELOPMENT-GUIDELINES.md</code>: deep dive into architecture, RPCD, ubus, CSS/JS conventions, and deployment (see summary in <code>DOCS/DOCUMENTATION-INDEX.md:68-82</code>).</li>
<li><code>DOCS/MODULE-IMPLEMENTATION-GUIDE.md</code> + <code>DOCS/FEATURE-REGENERATION-PROMPTS.md</code>: regeneration workflow plus ready-to-use prompts for all modules (<code>DOCS/DOCUMENTATION-INDEX.md:102-149</code>).</li>
<li><code>DOCS/CODE-TEMPLATES.md</code>: copy/paste-safe scaffolding for LuCI JS, RPCD scripts, and APIs (<code>DOCS/DOCUMENTATION-INDEX.md:153-159</code>).</li>
<h3id="non-negotiables-bake-into-every-prompt-or-pr">Non-Negotiables (bake into every prompt or PR)<aclass="headerlink"href="#non-negotiables-bake-into-every-prompt-or-pr"title="Permanent link">¶</a></h3>
<ul>
<li>RPCD filename <strong>must</strong> equal the ubus object (prevents <code>-32000 Object not found</code>, <code>DOCS/QUICK-START.md:11-18</code>).</li>
<li>Menu JSON <code>path</code><strong>must</strong> mirror the view path (avoids 404s, <code>DOCS/QUICK-START.md:20-26</code>).</li>
<li>Always run <code>./secubox-tools/validate-modules.sh</code> before opening PRs or tagging builds (reinforced in <code>README.md:18-23</code> and <code>DOCS/QUICK-START.md:122-134</code>).</li>
<li>Keep design tokens consistent: dark palette (<code>#0a0a0f</code> base, <code>#6366f1→#8b5cf6</code> gradients), Inter + JetBrains Mono fonts, <code>.sh-*</code>/<code>.sb-*</code> components, and responsive grid widths defined in the quick start (<code>DOCS/QUICK-START.md:74-114</code>).</li>
</ul>
<h3id="validation-toolchain-flow">Validation & Toolchain Flow<aclass="headerlink"href="#validation-toolchain-flow"title="Permanent link">¶</a></h3>
<ol>
<li><strong>Permissions Repair (local/remote):</strong><code>./secubox-tools/fix-permissions.sh --local|--remote</code> for automated chmod sanity (<code>DOCS/QUICK-START.md:55-66, 125-127</code>).</li>
<li><strong>Full Validation:</strong><code>./secubox-tools/validate-modules.sh</code> (runs seven structural checks including permission scan) (<code>DOCS/QUICK-START.md:122-134,185-189</code>).</li>
<li><strong>Module Builds:</strong><code>./secubox-tools/local-build.sh build <module></code> for quick smoke tests or <code>make package/<module>/compile V=s</code> inside SDK (<code>DOCS/QUICK-START.md:135-143</code>).</li>
<li><strong>Deploy/Fix:</strong> Copy to router via <code>scp</code>, normalize perms, flush <code>luci</code> caches, restart <code>rpcd</code>/<code>uhttpd</code> (<code>DOCS/QUICK-START.md:144-167</code>).</li>
<li><strong>Debug:</strong> Validate ubus objects, inspect LuCI resources, and tail <code>logread</code> immediately after deployment (<code>DOCS/QUICK-START.md:156-167</code>).</li>
</ol>
<h3id="design-ux-reminders">Design & UX Reminders<aclass="headerlink"href="#design-ux-reminders"title="Permanent link">¶</a></h3>
<ul>
<li>Stats tiles minimum 130px width, metrics 240px, detail cards 300px: encode these CSS grid rules to keep dashboards fluid on 720p+ viewports (<code>DOCS/QUICK-START.md:105-114</code>).</li>
<li>Buttons, tabs, and cards expose <code>.sh-</code> utility classes; prefer gradient borders and neon states over inline styles for maintainability (same section).</li>
<li>Align copy with README taxonomy (Core Control, Security & Monitoring, Network Intelligence, etc.) so documentation and UI stay in sync (<code>README.md:37-152</code> excerpt).</li>
<p>When drafting Codex/LLM prompts, supply enough structure so the assistant can reuse existing patterns instead of inventing them. Reuse this outline:</p>
<aid="__codelineno-0-16"name="__codelineno-0-16"href="#__codelineno-0-16"></a>- Note TODO items or documentation standards (version headers, cross-links, etc.).
<aid="__codelineno-0-17"name="__codelineno-0-17"href="#__codelineno-0-17"></a>- Remind Codex where to log changes (README, module changelog, etc.).
</code></pre></div>
<p>Pair the template with module-specific prompts from <code>DOCS/FEATURE-REGENERATION-PROMPTS.md</code> and the workflow from <code>DOCS/MODULE-IMPLEMENTATION-GUIDE.md</code> (<code>DOCS/DOCUMENTATION-INDEX.md:102-149</code>). That combination lets Codex inherit existing layout structures, RPCD shells, and API modules without brittle guesswork.</p>
<hr/>
<h2id="help-troubleshooting">Help & Troubleshooting<aclass="headerlink"href="#help-troubleshooting"title="Permanent link">¶</a></h2>
<ul>
<li><strong>Pre-deploy Sanity:</strong> 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 (<code>DOCS/QUICK-START.md:40-53</code>).</li>
<li><strong>Common Error Fixes:</strong> Keep the quick fixes near: HTTP 403 (chmod assets), “No space left” (purge <code>/tmp/*.ipk</code> and backups), ubus <code>-32000</code> (chmod 755 + ubus list). Automate via <code>secubox-tools</code> whenever possible (<code>DOCS/QUICK-START.md:55-70,171-180</code>).</li>
<li><strong>Design Drift:</strong> If CSS feels inconsistent, cross-check against the palette/fonts/components found in this manual and in the design section of the quick start (<code>DOCS/QUICK-START.md:74-114</code>).</li>
<li><strong>Need Examples?:</strong> Pull actual JS/RPCD snippets from <code>DOCS/CODE-TEMPLATES.md</code> or live modules under <code>luci-app-*</code> to keep generated code idiomatic (<code>DOCS/DOCUMENTATION-INDEX.md:153-159</code>).</li>
<li><strong>Still Blocked?:</strong><code>DOCS/DEVELOPMENT-GUIDELINES.md</code> holds the long-form reasoning for every standard; cite relevant sections when escalating issues so maintainers see the source of truth quickly (<code>DOCS/DOCUMENTATION-INDEX.md:68-82</code>).</li>
<li><strong>2025-12-26 – Full Dev Guides Released:</strong> README announces the arrival of the comprehensive dev guides set (README badge section, <code>README.md:7-16</code>).</li>
<li><strong>2025-12-27 – Documentation Index v1.0.0:</strong> Central index formalized the document map and AI workflow branches (<code>DOCS/DOCUMENTATION-INDEX.md:1-31</code>).</li>
<li><strong>2025-12-28 – Documentation Improvement Plan:</strong><code>TODO-ANALYSE.md</code> generated to coordinate versioning, cross-links, and archival tasks (<code>TODO-ANALYSE.md:1-34,71-150</code>).</li>
<li><strong>2025-12-28 – Codex Manual Drafted:</strong> This CODEX field manual formalizes how automation agents should operate going forward.</li>
<li><strong>Standardize version headers & dates</strong>– ensure every <code>.md</code> shows <code>Version/Last Updated/Status</code> with consistent <code>YYYY-MM-DD</code> formatting; DOCUMENTATION-INDEX must describe the policy once updates land (<code>TODO-ANALYSE.md:24-68</code>).</li>
<li><strong>Add “See Also” cross-links</strong>– 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 (<code>TODO-ANALYSE.md:71-116</code>).</li>
<li><strong>Archive historical docs</strong>– create <code>docs/archive/</code>, move outdated references (COMPLETION_REPORT, MODULE-ENABLE-DISABLE-DESIGN, BUILD_ISSUES, etc.), and drop an archive README describing contents (<code>TODO-ANALYSE.md:120-153</code>).</li>
<li><strong>Future work (Monthly/Quarterly)</strong>– new diagrams, TESTING/SECURITY/PERFORMANCE guides, automation for doc freshness, and i18n decisions are queued later in <code>TODO-ANALYSE.md</code>; mention them when prompts may impact scope or format downstream.</li>
</ol>
<p>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).</p>
<hr/>
<h2id="quick-reference-checklist-for-codex-runs">Quick Reference Checklist for Codex Runs<aclass="headerlink"href="#quick-reference-checklist-for-codex-runs"title="Permanent link">¶</a></h2>
<ulclass="task-list">
<liclass="task-list-item"><labelclass="task-list-control"><inputtype="checkbox"disabled/><spanclass="task-list-indicator"></span></label> Confirm the request references the right guide/template to minimize hallucinations (<code>DOCS/DOCUMENTATION-INDEX.md</code> paths).</li>
<liclass="task-list-item"><labelclass="task-list-control"><inputtype="checkbox"disabled/><spanclass="task-list-indicator"></span></label> Copy/paste the non-negotiables + validation flow into the prompt.</li>
<liclass="task-list-item"><labelclass="task-list-control"><inputtype="checkbox"disabled/><spanclass="task-list-indicator"></span></label> State which TODO radar items the change advances (or at least does not regress).</li>
<liclass="task-list-item"><labelclass="task-list-control"><inputtype="checkbox"disabled/><spanclass="task-list-indicator"></span></label> Cite commands/scripts to run post-change.</li>
<liclass="task-list-item"><labelclass="task-list-control"><inputtype="checkbox"disabled/><spanclass="task-list-indicator"></span></label> Capture findings in PR/commit descriptions referencing this CODEX manual when relevant.</li>
</ul>
<p>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.</p>
<scriptid="__config"type="application/json">{"annotate":null,"base":"..","features":["navigation.instant","navigation.tracking","navigation.tabs","navigation.tabs.sticky","navigation.sections","navigation.expand","navigation.top","search.suggest","search.highlight","content.code.copy","content.code.annotate"],"search":"../assets/javascripts/workers/search.2c215733.min.js","tags":null,"translations":{"clipboard.copied":"Copied to clipboard","clipboard.copy":"Copy to clipboard","search.result.more.one":"1 more on this page","search.result.more.other":"# more on this page","search.result.none":"No matching documents","search.result.one":"1 matching document","search.result.other":"# matching documents","search.result.placeholder":"Type to start searching","search.result.term.missing":"Missing","select.version":"Select version"},"version":{"provider":"mike"}}</script>
