Initial create

CODING-GUIDELINES.md

@@ -0,0 +1,53 @@
+# Coding Guidelines
+
+**Project:** kane-diagnostics  
+**Version:** 1.0
+
+These guidelines apply to all code in this project. They exist to keep the codebase readable, maintainable, and honest about what it does and does not do.
+
+---
+
+## 1. Limit individual code files to ~500 lines
+
+When a file approaches 500 lines it is signaling that a responsibility needs to be separated — not that the limit needs to be raised. Extract the responsibility into a new file with a clear name. The 500-line limit does not apply to JSON or markdown files.
+
+## 2. Use interfaces and contracts to connect components
+
+Every boundary between components has a named contract defined in JSON. The addon does not know how the orchestrator works. The orchestrator does not know how the addon works. Both know the contract between them. When a contract changes, the version number increments. Nothing connects to anything else directly.
+
+## 3. Use vendor code — pin versions explicitly
+
+Do not write what already exists. When a vendor library is used, pin the version number in the filename and in `hubzilla/addon/vendor/README.md`. An unpinned dependency is a reliability risk that grows silently over time.
+
+## 4. Define limitation by Hubzilla capacity — orchestrate the rest
+
+Hubzilla does: authentication, routing, rendering, ACL, session management, privacy groups.  
+Hubzilla does not do: data persistence, background processing, IPFS, external API calls, file indexing.  
+Anything that crosses that boundary belongs on the orchestrator. If it feels like the addon is doing too much, it probably is.
+
+## 5. Use JSON as the pilot of the database schema
+
+Define the data structure in JSON first. Use it in the addon. Validate it with real usage. Only then commit it to a MariaDB schema. A JSON file that works is a schema that is already proven.
+
+## 6. One addon, one purpose
+
+Each addon has exactly one job. It does not share database tables with other addons. It does not call other addons directly. Communication between addons happens through the orchestrator. If an addon is doing two things, it should be two addons.
+
+## 7. No inline styles, no inline scripts
+
+All CSS lives in `view/css/{addon}.css`.  
+All JS lives in `view/js/{addon}.js`.  
+Inline styles and inline scripts are prohibited. They cannot be cached, they cannot be debugged cleanly, and they fight each other in ways that are difficult to trace.
+
+## 8. Configuration over code
+
+Anything that might differ between installations — group IDs, endpoint URLs, tokens, thresholds, feature flags — lives in `config.json`. It is never hardcoded. The `config.json.template` in the repo shows every field. The live `config.json` on the host is never committed to the repo.
+
+## 9. Fail visibly, fail safely
+
+When a file cannot be read, when the config is missing, when the orchestrator is unreachable — the addon shows a clear, plain-language message to the operator or participant. It never shows a blank page, a PHP stack trace, or a silent failure. The error is diagnostic information.
+
+## 10. Markdown for ideas, comments for guides
+
+Markdown documents state the purpose and boundary of their subject. Nothing more. They do not describe implementation details — those belong in the code.  
+Every function has a single-line comment stating what it does and what it does not do. No paragraph-length comments. No commented-out code. Documentation that is not in the code goes stale faster than the code does.