kane-diagnostics/ADDON-SKELETON-SPEC.md

Addon Skeleton Specification

Project: kane-diagnostics
Version: 2.0
Prerequisite reading: README.md, DSC-development-map.md, HANDOFF.md, CODING-GUIDELINES.md, INSTITUTIONAL-RELATIONSHIPS.md, FOR-PARTICIPANTS-AND-PROFESSIONALS.md

---

The Standard

This document defines the skeleton standard for all Kane Diagnostics Hubzilla addons — present and future. The three addons described below are the first implementations of the standard, not the definition of it. Any addon added to this project follows the same skeleton: same file layout, same Widget structure, same PDL pattern, same config template fields, same spool contract discipline, same coding constraints.

The standard changes only by deliberate revision of this document. A revised document increments the version number and is committed to the repo. The previous version is never deleted — it remains as the historical record of what was built under it.

If you are reading this document and the repo contains addon code, read the code before reading this document any further. The code is the ground truth. This document describes what the code should look like. When they conflict, ask the operator before proceeding.

Nothing in this document should be built without the operator's input and confirmation at each step.

---

The Three Addons

vs01 — Vital Signs

Purpose: Present the ten structural preconditions of an HOA association. Public-facing — readable without authentication. This is the first thing a participant reads and the first thing an attorney reads.

Route: /vs01

Access: Public read. No authentication required to view. HOA_MEMBER standing required to submit a Vital Signs record for a specific association.

What it does:

• Presents each of the ten Vital Signs in plain language
• Explains why each one matters to the homeowner
• Provides public record lookup guidance for each Vital Sign (Recorder of Deeds, Secretary of State, IDFPR, etc.)
• Allows a verified participant to submit a Vital Signs record for their association
• Stores the record via the orchestrator spool

What it does not do:

• It does not present scenarios
• It does not present case law
• It does not manage the institutional directory

---

dsc01 — Diagnostic Surface Categories

Purpose: Present the Diagnostic Surface Categories — the legal surfaces where HOA governance disputes manifest — organized from the homeowner's perspective. Browsable publicly. Case law entries require HOA_MEMBER standing to submit.

Route: /dsc01

Access: Public read. HOA_MEMBER standing required to submit a diagnostic record or case law entry.

What it does:

• Presents the ten Active DSC categories with their diagnostic questions
• Presents the Vital Sign dependencies for each category
• Presents case law entries organized by DSC category
• Connects each DSC category to the relevant Vital Signs
• Allows verified participants to submit accounts under a specific DSC category
• Stores records via the orchestrator spool

What it does not do:

• It does not present scenarios
• It does not manage the Vital Signs record
• It does not manage the institutional directory

---

scn01 — Scenarios

Purpose: The participant intake surface. A verified participant reads diagnostic scenarios, writes their account in their own words, and submits. The account is the record.

Route: /scn01

Access: HOA_MEMBER standing required. Public visitors see the access wall with SASE instructions.

What it does:

• Presents the scenario carousel — browse only, no selection required
• Accepts the participant's account in their own words
• Writes the submission to the orchestrator spool as a TMP record
• Provides an operator-only /scn01/manage interface for scenario management and TMP review

What it does not do:

• It does not present Vital Signs
• It does not present case law
• It does not manage the institutional directory

Relationship to pilot:
The pilot ds01 addon in caselaw-document-access is the functional prototype for this addon. The new scn01 is a clean rebuild on the complete foundation — not a port of the pilot code. The pilot is reference, not source.

---

Skeleton File Structure

Each addon skeleton follows this structure. Files marked [placeholder] contain the correct structure but no functional logic.

hubzilla/addon/{addon}/
  {addon}.php               — main addon file: hooks, load/unload, content routing
  {addon}.apd               — app descriptor
  mod_{addon}.pdl           — PDL layout: aside, content, right_aside
  config.json.template      — all config fields documented, no secrets
  listings.json.template    — institutional directory schema, Core slots pre-populated
  Widget/
    {Addon}.php             — sidebar widget: the institutional directory
  view/
    css/
      {addon}.css           — all presentation styles, no inline styles anywhere
    js/
      {addon}.js            — all behavior, no inline scripts anywhere
  contracts/
    spool-v1.json           — the spool envelope contract this addon produces
  README.md                 — one paragraph: what this addon does and does not do

---

Skeleton Content Requirements

{addon}.php

Must contain, in order:

1. File header — addon name, description, version, min/max Hubzilla version
2. Hook registration — {addon}_load() and {addon}_unload() with PDL and Widget hooks
3. PDL loader — {addon}_load_pdl() following the established convention
4. Helper — {addon}_h() — the HTML escape function
5. Access state — {addon}_access_state() — returns 'public', 'participant', or 'operator'
6. Access wall — {addon}_access_wall() — plain language, SASE link
7. Content router — {addon}_content() — loads CSS/JS, checks access, routes by path and method
8. Config loader — {addon}_load_config()
9. Listings loader — {addon}_load_listings() — reads listings.json, returns structured array; fails visibly if file is missing or malformed
10. CSRF token and verify — standard pattern
11. Placeholder content functions — one per route, each returning a // TODO string with a plain description of what goes here

No functional logic in the skeleton. No database calls. No file I/O beyond config and listings loaders. No orchestrator calls. Those come after the skeleton is confirmed.

{addon}.apd

version: 2
url: $baseurl/{addon}
requires: local_channel
name: {Descriptive name}
photo: icon:{bootstrap-icon-name}
categories: Civic Diagnostics
desc: {One sentence — what this addon does.}

mod_{addon}.pdl

[template]default[/template]

[region=aside]
[widget={addon}][/widget]
[/region]

[region=content]
$content
[/region]

[region=right_aside]
[widget=notifications][/widget]
[widget=newmember][/widget]
[/region]

The right_aside is permanent and identical across all addons. It is never modified.

config.json.template

Every field the addon reads from config.json must appear here with a descriptive comment and a placeholder value. No field should ever be read from config.json that does not first appear in config.json.template.

{
  "_note": "Copy to config.json. Do not commit config.json — it contains secrets and installation-specific values.",
  "receiver_url": "REPLACE — orchestrator receiver endpoint",
  "node_token": "REPLACE — shared secret for node-to-orchestrator auth",
  "corpus_builder_group_id": 0,
  "listings_file": "REPLACE — absolute path to listings.json on the host"
}

listings.json.template

The institutional directory schema. This file documents the structure. The live listings.json on the host is operator-managed and never committed to the repo.

The Core tier always contains exactly three slots. They are permanent. They render whether populated or not. An unpopulated slot displays its role description and invitation text. No entity name or mark appears until the operator records written approval and populates the entry.

{
  "_note": "Copy to listings.json on the host. Do not commit listings.json — it contains entity names and approval records that are operator-managed.",
  "_version": "1.0",
  "core": [
    {
      "slot": "taxonomy-authority",
      "role": "Taxonomy Authority",
      "description": "The institutional source of the case law categories this diagnostic record is organized by.",
      "status": "pending",
      "name": null,
      "mark_url": null,
      "url": null,
      "approved_date": null
    },
    {
      "slot": "methodology-certifier",
      "role": "Methodology Certifier",
      "description": "The law firm whose professional association with this project certifies the diagnostic record meets a standard the legal community can use.",
      "status": "pending",
      "name": null,
      "mark_url": null,
      "url": null,
      "approved_date": null
    },
    {
      "slot": "peer-operator",
      "role": "Peer Operator",
      "description": "The cooperating Civic Infrastructure host who can independently verify, support, and if necessary continue this diagnostic record.",
      "status": "pending",
      "name": null,
      "mark_url": null,
      "url": null,
      "approved_date": null
    }
  ],
  "tier1": [],
  "tier2": [],
  "other": []
}

Entry schema for Tier-I, Tier-II, and Other:

{
  "id": "REPLACE — unique identifier, e.g. t1-001",
  "role": "REPLACE — e.g. Mediator, Attorney, Civic Organization",
  "name": "REPLACE — display name",
  "description": "REPLACE — one sentence describing this entity's practice",
  "url": "REPLACE — public URL",
  "qualifying_case": "REPLACE — Tier-II attorneys only: case citation from public record",
  "listed_date": "REPLACE — ISO date of listing",
  "approved_date": "REPLACE — ISO date of written approval"
}

Widget/{Addon}.php

The Widget renders the institutional directory in the left aside. This is its only job.

Must contain:

• Correct namespace: namespace Zotlabs\Widget;
• Class name matching filename exactly: class {Addon}
• widget($arr) method returning sidebar HTML
• render_directory() — loads listings via {addon}_load_listings(), renders the four-tab structure
• render_core_tab() — always renders all three Core slots; pending slots show role description and invitation text
• render_tier_tab($entries, $placeholder) — renders entries if any exist; renders placeholder text if none
• h($value) — local HTML escape method

The Widget does not render navigation. It does not render a steps indicator. It does not render resource panels. Those patterns belong to the pilot and do not transfer.

Tab structure

Four horizontal Bootstrap nav-tabs across the top of the aside:

Tab	Label	Content
Core	Core	Three permanent slots — Taxonomy Authority, Methodology Certifier, Peer Operator
Tier-I	Tier-I	Mediators, subject matter experts, advisors, authors
Tier-II	Tier-II	Attorneys — qualification standard per INSTITUTIONAL-RELATIONSHIPS.md
Other	Other	Civic organizations, consumer protection entities, oversight agencies

The default active tab is Core. The operator may specify a different default per addon in config.json via a directory_default_tab field — this field is listed in config.json.template with value "core".

A pending Core slot renders:

<div class="{addon}-directory-slot {addon}-slot-pending">
  <div class="{addon}-slot-role">{role}</div>
  <div class="{addon}-slot-description">{description}</div>
  <div class="{addon}-slot-status">Invitation pending</div>
</div>

A populated Core slot renders the entity name, mark (if provided), and URL. It never renders until status is "active" in listings.json.

contracts/spool-v1.json

The JSON contract this addon produces and POSTs to the orchestrator. Must contain:

• _header block with all required fields documented
• _payload block with the addon-specific fields
• _meta block describing the contract version and purpose

This file is the contract. When the payload structure changes, the version increments and a new file is created (spool-v2.json). The old contract is never deleted — it documents what the orchestrator must remain able to consume.

{addon}.css

Skeleton contains:

• File header comment with addon name and version
• Section comments for each visual area: layout, header, content, aside, directory, directory-core, directory-tiers, manage
• No rules yet — just the section comments as placeholders

{addon}.js

Skeleton contains:

• IIFE wrapper
• initDirectory() function — placeholder, // TODO: Bootstrap tab init if needed beyond data-bs-toggle
• One placeholder function per interactive area with a // TODO comment
• init() calling all functions
• DOMContentLoaded guard

The pilot's initResourcePanels() function does not transfer. The new addons have no resource panels.

---

Build Sequence

The operator will direct which addon to build first. The expected sequence based on the DSC development map is:

1. vs01 — Vital Signs — because it is the entry point for both participants and attorneys
2. dsc01 — DSC Categories — because it is the primary reference surface
3. scn01 — Scenarios — because it depends on both Vital Signs and DSC context being established

Each skeleton must be confirmed working — loading without errors, displaying the access wall or placeholder content correctly, rendering all four directory tabs including the three pending Core slots — before the next skeleton begins.

---

What the Operator Will Decide Before Each Skeleton Is Built

Before writing any skeleton file, discuss and confirm with the operator:

1. The exact route — the operator may have a different preference than what is proposed here
2. The access model — which privacy group gates participant access for this addon
3. The default directory tab — which of the four tabs is active on first load for this addon's typical visitor
4. The config fields — whether any addon-specific configuration is needed beyond the standard fields
5. The spool contract — what the payload block contains for this addon's submissions

Do not assume these decisions are made because they appear in this document. This document proposes. The operator decides.

---

What Not To Do

• Do not port the pilot ds01 code. Read it as reference for Hubzilla conventions. Write the skeleton fresh.
• Do not add functional logic to the skeleton. Placeholders only.
• Do not generate all three skeletons at once. One at a time, confirmed working before the next begins.
• Do not create files that already exist in the repo. Read the repo first.
• Do not hardcode any value that belongs in config.json.
• Do not write inline styles or inline scripts.
• Do not exceed 500 lines in any PHP file. The skeleton should be well under that — if it is approaching 300 lines before any logic is added, something is wrong.
• Do not build the Widget without all four directory tabs present and the three Core slots rendering. The directory is not a feature added after the skeleton is confirmed. It is part of what makes the skeleton complete.
• Do not populate Core slots with entity names. Pending state is the correct skeleton state. Names appear only after written approval is recorded by the operator.