@rubytech/create-sitedesk-code 0.1.340

package/payload/premium-plugins/sitedesk/plugins/sitedesk-job/skills/valuation/references/issue-flow.md

@@ -0,0 +1,117 @@
+# Issuing a valuation — the per-cycle lifecycle
+
+Issuing valuation N+1 is a write-render-ingest lifecycle. Because it touches three carriers of
+the same truth (the graph, the filed PDF, and `engine-state.json`), every step is instrumented
+on one correlation key so a failed issue is diagnosable from logs alone:
+
+```
+valKey = {jobId}:{valuationNumber}
+```
+
+## The cycle delta
+
+A cycle consumes a delta over the prior carried state — never a fresh full state. The delta
+carries the cycle's identity and only what changed this cycle:
+
+- `valuationNumber` and `date` — the number being issued (N+1) and its date. The engine copies
+  both straight onto the computed valuation, and the document header requires them (see
+  [document.md](document.md)); a delta missing either yields an unnumbered/undated valuation that
+  the reconcile gate (totals only) will not catch.
+- per-line new `% complete` and, where the operator's document carries a comment column, the new
+  per-line comment (`lineUpdates`, keyed on the line `id`);
+- per-open-variation new `% complete` (`variationUpdates`, keyed on the variation `number`);
+- new variations (`newVariations`);
+- new payments received (`newPayments`).
+
+The roll-up engine applies the delta and emits the figures plus the `nextState`; see
+[roll-up.md](roll-up.md) for the engine and [job-folder.md](job-folder.md) for the carried shape.
+
+## Variations are value-agnostic (a mix)
+
+Two kinds of variation arrive in the same register, and both land as one `:VariationNote`:
+
+- An **engine-priced** variation is priced through the `quotation` skill's pricing engine first,
+  then recorded with `priced: true`.
+- An **entered agreed-value** variation (for example a day-rate agreed on site) is recorded
+  directly with `priced: false`, its narrative captured **verbatim** in the comment.
+
+On the node, the signed value goes to `:VariationNote.amount`, the narrative to `description`,
+and the operator's own state word to `status`. The per-variation `% complete` is **not** a node
+property — it is carried cycle state in `engine-state.json` and the `:Valuation` snapshot body.
+The per-line comment column, when the operator's document carries one, is carried the same way:
+cycle state, never a node property.
+
+## The lifecycle and its observability
+
+Emit each op in order, on `valKey`:
+
+1. `op=request valKey=… jobId=… n=… priorN=…` — before any work.
+2. `op=state-loaded valKey=… lines=<count> variations=<count> paymentsToDate=<sum>` — the
+   carried baseline this cycle builds on.
+3. `op=delta valKey=… linesUpdated=<n> variationsAdded=<n> paymentsAdded=<n>` — surfaces an
+   empty or partial delta on the first occasion.
+4. `op=rollup valKey=… gross=… lessPayments=… net=… vat=… total=… outstanding=… anticipatedFinal=…`
+   — the authoritative figures, logged before render.
+5. `op=reconcile valKey=… computedTotal=… renderedTotal=… match=<bool>`; on `match=false` →
+   `op=reconcile-fail` and **stop** — no file, no ingest, no `:Valuation` committed as issued.
+   The engine's own stdout is the un-keyed half of this pair — `op=reconcile match=true
+   computedTotal=… renderedTotal=…` on success, `op=reconcile-fail computedTotal=…
+   renderedTotal=…` on mismatch (it cannot know `valKey`); the agent re-emits the line above with
+   `valKey` so the lifecycle is greppable on one key.
+6. `op=valuation-written valKey=… elementId=…` (graph) and `op=state-saved valKey=… path=…`
+   (`engine-state.json` rewritten from `nextState`).
+7. `op=pdf-saved valKey=… path=… bytes=…` — assert non-zero bytes from the
+   `Saved PDF to <path> (<bytes>)` line before treating the PDF as done.
+8. `op=ingested valKey=… kdId=… sections=<n>` — the retrieval anchor.
+9. `op=exit valKey=… ranMs=… outcome=<issued|reconcile-fail|error>`.
+
+**No-content-loss capture.** Every input region the cycle could **not** confidently encode — an
+ambiguous percent, a variation with no value, a payment with no reference — is logged
+`op=uncaptured valKey=… region=… reason=…` so the gap is seen at issue time, not later in a wrong
+document.
+
+## The graph write
+
+Write the `:Valuation` idempotently on the **natural key** `(accountId, jobId, valuationNumber)`,
+so re-issuing a valuation number overwrites cleanly rather than duplicating. The natural key, not
+any Neo4j `elementId`, is the identity the skill depends on — an `elementId` can be reused after
+an unrelated purge, so nothing keys off it. Carry the per-line and per-variation snapshot in the
+`:Valuation` snapshot body (not as new labels).
+
+Connect the `:Valuation` to its job with the canonical edge `(:Job)-[:HAS_VALUATION]->(:Valuation)`
+— never an invented type such as `VALUATION_FOR`. Link the lines this valuation measures with
+`(:Valuation)-[:VALUES]->(:LineItem)`, reading those lines through the quote
+(`(:Job)-[:HAS_QUOTE]->(:QuoteDocument)-[:HAS_LINE_ITEM]->(:LineItem)`) — line items belong to the
+`:QuoteDocument`, never written directly onto the `:Job`. The edge types are fixed by
+`schema-construction.md`; write no edge type absent from it. Account scope is the `accountId`
+property, never an ownership edge.
+
+A `:Valuation` is **re-assertable** from its other two carriers: a filed PDF and the carried
+state for a valuation number whose node is absent must reproduce the node — idempotently on the
+same natural key — rather than stay missing. The node is derived data; the filed PDF and the
+carried state are the durable record it is re-asserted from.
+
+## Filing and ingestion
+
+File the rendered HTML and PDF in that valuation's own folder under `Finances/Valuations/` —
+`Finances/Valuations/Valuation {jobId}-{NN}/` (see [job-folder.md](job-folder.md)). Then ingest
+the filed PDF as a `:KnowledgeDocument` for retrieval across the job's history, using the memory
+plugin's document-ingest path: `memory-ingest-extract` to pull the text, in-turn section
+classification against the ontology, then `memory-ingest` to write the `:KnowledgeDocument` and
+its `:Section` nodes with embeddings. Only a reconciled, filed valuation is ingested.
+
+## Standing census (no-event drift)
+
+A `:Valuation` written with no filed PDF, or a PDF with no node, is a silent failure that emits
+no per-action log and never reproduces on demand. A periodic per-job audit reconciles the three
+carriers and is the only thing that catches it:
+
+```
+[valuation-census] jobId=… graphN=<:Valuation count> filedN=<PDFs under Finances/Valuations/> stateN=<engine-state.json sequence length> consistent=<bool>
+```
+
+`consistent=false` is the divergence signature. The census does not just report it: a valuation
+number present in the filed PDFs and the carried state but missing from the graph is **re-asserted**
+on its natural key on the next census or issue (see The graph write), so a node lost to `elementId`
+reuse after a purge reproduces rather than staying silently absent. Investigate any job whose three
+counts still disagree after the re-assert.

package/payload/premium-plugins/sitedesk/plugins/sitedesk-job/skills/valuation/references/job-folder.md

@@ -0,0 +1,91 @@
+# The job folder — `$ACCOUNT_DIR/jobs/{jobId}/`
+
+A job is the hub for everything a contractor's job accumulates over its life. One folder per
+job, addressed by `jobId`, holds the quote it started from, every interim valuation it has
+issued, the source documents it was built from, and the single carried state the next cycle
+reads.
+
+```
+$ACCOUNT_DIR/jobs/{jobId}/
+├── quote/                              the originating quote and all its versions
+├── Finances/
+│   └── Valuations/
+│       ├── engine-state.json          the carried truth between cycles (at this root)
+│       ├── Valuation {jobId}-01/
+│       │   ├── valuation-1.html
+│       │   ├── valuation-1.pdf
+│       │   ├── computed-1.json
+│       │   └── delta-1.json
+│       └── Valuation {jobId}-02/ …
+├── source/                            ingested tender, instruction emails, photos
+```
+
+Each issued valuation has its own folder, `Valuation {jobId}-{NN}` with the sequence number
+zero-padded to two digits, holding that valuation's HTML, PDF, computed JSON and delta JSON. The
+set of valuation folders grows without limit — there is no fixed ceiling on the valuation count;
+a job at valuation 32 simply has `Valuation {jobId}-01 … Valuation {jobId}-32`, and the next
+issue writes `Valuation {jobId}-33`. The job-level carried state, `engine-state.json`, sits at
+the `Finances/Valuations/` root — **not** inside any per-valuation folder, because it belongs to
+the job, not to one valuation.
+
+The folder layout and naming above is the structure the skill expects, and in a fully
+operator-learned model the layout itself may be a learned, configurable convention. What is
+**universal** is that the three carriers of the same valuation — the graph `:Valuation` node,
+the filed PDF, and the carried state — stay reconcilable per the standing census (see
+[issue-flow.md](issue-flow.md)).
+
+## `engine-state.json` — the carried truth
+
+`engine-state.json` is the one place a job's carried figures live between cycles. It is the
+input the roll-up engine reads, and it is rewritten from the engine's `nextState` **only after**
+a valuation has reconciled and been filed (see [roll-up.md](roll-up.md) and
+[issue-flow.md](issue-flow.md)). **All money is integer pence** — never pounds, never floats —
+so the roll-up reconciles to the penny.
+
+```json
+{
+  "jobId": "1737",
+  "contractSumPence": 0,
+  "vatRatePct": 20,
+  "retentionPct": 5,
+  "roundingPolicy": "round-then-vat",
+  "lines": [
+    { "id": "L1", "description": "Substructure", "contractValuePence": 0, "pctComplete": 0, "comment": "" }
+  ],
+  "variations": [
+    { "number": "V1", "valuePence": 0, "pctComplete": 0, "comment": "", "status": "open", "priced": false }
+  ],
+  "paymentsReceived": [
+    { "ref": "", "amountPence": 0, "date": "2026-01-01" }
+  ]
+}
+```
+
+Field meaning:
+
+- `contractSumPence` — the full original contract sum (the sum of the contract-works line values
+  plus provisional sums). Fixed at job setup; it does not move with progress.
+- `vatRatePct`, `retentionPct` — recorded at setup. `retentionPct` is **carried but not applied**
+  by the roll-up (retention release is out of scope); see [roll-up.md](roll-up.md).
+- `roundingPolicy` — the operator's rounding convention, `round-then-vat` or
+  `full-precision-then-round`; read by the engine and captured when the document is learned (see
+  [roll-up.md](roll-up.md) and [document-learning.md](document-learning.md)). Absent ⇒ the
+  engine's `round-then-vat` default.
+- `lines[]` — the contract-works schedule. `contractValuePence` is the line's fixed contract
+  value; `pctComplete` is the cumulative percent complete carried into this cycle. `comment` is
+  the operator's free-text narrative for the line **this cycle** — carried cycle state, present
+  only when the operator's document carries a per-line comment column, empty otherwise (it is
+  **not** a node property; see [issue-flow.md](issue-flow.md)).
+- `variations[]` — the append-only variations register. `valuePence` is the agreed value,
+  **signed** — a negative value is an omit or discount and is first-class. `pctComplete` is the
+  variation's cumulative percent complete. `comment` holds the operator's narrative verbatim.
+  `status` is the operator's own (e.g. `open`, `agreed`). `priced` records whether the value
+  came through the `quotation` skill's pricing engine (`true`) or was entered as an agreed value
+  (`false`).
+- `paymentsReceived[]` — operator-entered carried state: a list of payments received, each with
+  the operator's reference and the amount in pence. The roll-up sums it to payments-to-date;
+  nothing models it beyond the list and the sum.
+
+The `lines[].id` and `variations[].number` values are the keys the cycle delta updates against.
+The placeholder zeros above are shape, not seed data — a real `engine-state.json` carries the
+operator's own figures and never ships in this tree.

package/payload/premium-plugins/sitedesk/plugins/sitedesk-job/skills/valuation/references/roll-up.md

@@ -0,0 +1,73 @@
+# The deterministic roll-up
+
+The valuation arithmetic is universal quantity-surveying maths — the same for every
+contractor. It must reconcile to the penny, so it is computed by the shipped engine
+`rollup.mjs`, never by hand. The engine carries no operator content; it runs on whatever
+`state.json` and `delta.json` it is handed.
+
+## The figures, in order (integer pence)
+
+For each contract-works line: `line_cum = contractValue × % complete`.
+
+For each variation: `variation_cum = value × % complete`. The value is **signed**, so an omit
+(negative value) reduces the gross — negatives are first-class, not a special case.
+
+Then:
+
+- `gross = Σ line_cum + Σ variation_cum`
+- `net = gross − payments_received_to_date`
+- `vat = net × VAT rate`
+- `total = net + vat`
+- `outstanding = contract sum − payments_received_to_date` — the remaining contract value
+  still to bill (ex VAT). This is a contract balance, **not** this cycle's amount due; the
+  document's summary displays this engine figure and never assembles its own.
+- `anticipated_final = full contract sum + full variations total` — where "full" means each
+  variation at its whole agreed value, regardless of its percent complete.
+
+**Retention** is recorded in the carried state (`retentionPct`) but is **not** a term in this
+roll-up: `net` is `gross − payments`, with no retention deduction. Retention release is out of
+scope for this skill — do not invent a retention line in the maths.
+
+## Rounding policy
+
+The order in which the penny rounding is applied is itself a per-operator decision, because it
+can move a displayed total by a penny. The engine reads the policy from carried state
+(`roundingPolicy`) and supports two settings:
+
+- **`round-then-vat`** — round each `line_cum` and `variation_cum` to the penny, sum those
+  rounded figures, and apply VAT to the rounded net. Every intermediate figure is an exact
+  penny. This is the engine's default when no policy is carried.
+- **`full-precision-then-round`** — carry full precision through the gross, the net and the
+  VAT, and round only the figures shown on the document. Fractional pennies that
+  `round-then-vat` would settle line by line are instead settled once, at the total.
+
+Both are legitimate quantity-surveying conventions; which one an operator uses is **their**
+recorded choice, captured when their document is learned (see
+[document-learning.md](document-learning.md)) and carried in their own `engine-state.json` — it is
+never fixed in this skill. The two policies can disagree by a penny on the same figures, so the
+policy is part of what verification (see [document-verification.md](document-verification.md))
+must reproduce: a document learned under one policy is correct only when it reproduces the
+operator's own past valuations under that policy.
+
+## The engine
+
+```
+node rollup.mjs compute   <state.json> <delta.json>        # -> computed valuation JSON (stdout)
+node rollup.mjs reconcile <computed.json> <renderedPence>  # -> exit 0 match, exit 1 mismatch
+```
+
+`compute` applies the cycle delta over the carried state and emits the computed valuation: the
+per-line and per-variation cumulative figures, `grossPence`, `paymentsToDatePence`, `netPence`,
+`vatPence`, `totalPence`, `outstandingPence`, `anticipatedFinalPence`, and a `nextState` — the
+full carried state to write back to `engine-state.json` after the gate passes. `compute` is pure: the
+same inputs always yield the same output, so re-issuing a valuation number cleanly overwrites
+with identical figures.
+
+## The reconcile gate
+
+The rendered document is produced from the computed figures (see [document.md](document.md)).
+Before the valuation is treated as issued, `reconcile` compares the document's displayed total
+against `computed.totalPence`. On a match it exits zero. On a mismatch it exits nonzero and
+emits `op=reconcile-fail` — and the issue **stops**: no PDF is filed, nothing is ingested, and
+the `:Valuation` is not committed as issued. A valuation whose document disagrees with the
+compute is a defect, never a thing to ship.

package/payload/premium-plugins/sitedesk/plugins/sitedesk-job/skills/valuation/rollup.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// Deterministic interim-valuation roll-up. All money is integer pence, so the
+// figures reconcile to the penny. This removes the LLM from the arithmetic
+// path: figures are computed here, and `reconcile` is the hard gate that
+// refuses a rendered document whose displayed total disagrees with the compute.
+// Carries no operator content — it runs on whatever state.json/delta.json it is
+// handed.
+//
+//   node rollup.mjs compute   <state.json> <delta.json>      -> computed JSON (stdout)
+//   node rollup.mjs reconcile <computed.json> <renderedPence> -> exit 0 match / 1 mismatch
+//
+// Retention is carried in state (retentionPct) but is NOT applied here:
+// net = gross - payments, with no retention term. Retention release is out of
+// scope for this engine.
+import { readFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+// Round to the nearest penny, half away from zero — the conventional money
+// rounding. Symmetric for omits: +£x.xx5 and -£x.xx5 round to mirror values,
+// which Math.round (half toward +Inf) does not.
+const roundPence = (x) => Math.sign(x) * Math.round(Math.abs(x));
+// Full-precision proportion: no rounding. The rounding policy decides where the
+// rounding happens; this keeps the un-rounded value for the policy to act on.
+const rawPctOf = (pence, pct) => (pence * pct) / 100;
+
+export function compute(state, delta) {
+  // Apply the cycle delta over carried state; pure (returns figures + nextState).
+  const lines = state.lines.map((l) => {
+    const u = (delta.lineUpdates || []).find((x) => x.id === l.id);
+    return u ? { ...l, pctComplete: u.pctComplete } : { ...l };
+  });
+  const variations = state.variations.map((v) => {
+    const u = (delta.variationUpdates || []).find((x) => x.number === v.number);
+    return u ? { ...v, pctComplete: u.pctComplete } : { ...v };
+  });
+  for (const nv of delta.newVariations || []) variations.push({ ...nv });
+  const paymentsReceived = [...state.paymentsReceived, ...(delta.newPayments || [])];
+
+  // Rounding policy (carried per operator). Two settings, documented in
+  // references/roll-up.md; an absent or unknown value is the conservative
+  // round-then-vat default. The policy decides where the penny rounding lands,
+  // which is what produces (or avoids) a 1p divergence between the two methods.
+  //  - round-then-vat:          round each line/variation cum to the penny, sum,
+  //                             then VAT the rounded net (each step is integer).
+  //  - full-precision-then-round: carry full precision through gross, net and VAT,
+  //                             round only the emitted figures for display.
+  const fullPrecision = state.roundingPolicy === "full-precision-then-round";
+
+  // Per-row: keep the un-rounded cum, and a rounded cum for display. Lines and
+  // variations are always shown to the penny; the policy only changes whether
+  // the chain sums the rounded cums or the un-rounded ones.
+  const lineRows = lines.map((l) => {
+    const cumRaw = rawPctOf(l.contractValuePence, l.pctComplete);
+    return { ...l, cumPence: roundPence(cumRaw), cumRaw };
+  });
+  const varRows = variations.map((v) => {
+    const cumRaw = rawPctOf(v.valuePence, v.pctComplete);
+    return { ...v, cumPence: roundPence(cumRaw), cumRaw };
+  });
+
+  const grossChain = fullPrecision
+    ? lineRows.reduce((s, r) => s + r.cumRaw, 0) + varRows.reduce((s, r) => s + r.cumRaw, 0)
+    : lineRows.reduce((s, r) => s + r.cumPence, 0) + varRows.reduce((s, r) => s + r.cumPence, 0);
+  const paymentsToDatePence = paymentsReceived.reduce((s, p) => s + p.amountPence, 0);
+  const netChain = grossChain - paymentsToDatePence;
+  const vatChain = (netChain * state.vatRatePct) / 100;
+
+  const grossPence = roundPence(grossChain);
+  const netPence = roundPence(netChain);
+  const vatPence = roundPence(vatChain);
+  // round-then-vat sums two already-rounded pennies; full-precision rounds the
+  // full-precision (net + vat) once, which is what shifts the displayed total by
+  // a penny on a fixture that exercises it.
+  const totalPence = fullPrecision ? roundPence(netChain + vatChain) : netPence + vatPence;
+  // Anticipated final = full contract sum + full (100%) value of every variation.
+  const anticipatedFinalPence = state.contractSumPence + variations.reduce((s, v) => s + v.valuePence, 0);
+  // Outstanding = contract value still to bill = contract sum − payments received
+  // to date (ex VAT). It is the remaining contract balance, never this cycle's
+  // amount due; the summary displays this engine figure, it does not assemble
+  // its own.
+  const outstandingPence = state.contractSumPence - paymentsToDatePence;
+
+  // Drop the internal cumRaw from the emitted rows: the document displays the
+  // rounded cumPence, and cumRaw is a compute-internal carried only this far.
+  const stripRaw = ({ cumRaw, ...row }) => row;
+  const nextState = { ...state, lines, variations, paymentsReceived };
+  return {
+    valuationNumber: delta.valuationNumber,
+    date: delta.date,
+    lines: lineRows.map(stripRaw),
+    variations: varRows.map(stripRaw),
+    grossPence,
+    paymentsToDatePence,
+    netPence,
+    vatPence,
+    totalPence,
+    anticipatedFinalPence,
+    outstandingPence,
+    nextState,
+  };
+}
+
+function main(argv) {
+  const [cmd, a, b] = argv;
+  if (cmd === "compute") {
+    const state = JSON.parse(readFileSync(a, "utf8"));
+    const delta = JSON.parse(readFileSync(b, "utf8"));
+    process.stdout.write(JSON.stringify(compute(state, delta), null, 2));
+    return 0;
+  }
+  if (cmd === "reconcile") {
+    const computed = JSON.parse(readFileSync(a, "utf8"));
+    const renderedRaw = String(b).trim();
+    // The rendered total must be a clean integer-pence value. parseInt would
+    // silently accept "540000abc" or floor "540000.9" — both defeat the gate.
+    if (!/^-?\d+$/.test(renderedRaw)) {
+      process.stderr.write(`op=reconcile-fail reason=non-integer-rendered renderedTotal=${b}\n`);
+      return 1;
+    }
+    const rendered = Number(renderedRaw);
+    if (computed.totalPence === rendered) {
+      process.stdout.write(`op=reconcile match=true computedTotal=${computed.totalPence} renderedTotal=${rendered}\n`);
+      return 0;
+    }
+    process.stderr.write(`op=reconcile-fail computedTotal=${computed.totalPence} renderedTotal=${rendered}\n`);
+    return 1;
+  }
+  process.stderr.write(
+    "usage: rollup.mjs compute <state.json> <delta.json> | reconcile <computed.json> <renderedTotalPence>\n",
+  );
+  return 2;
+}
+
+// CLI entry only when run directly (not when imported). Compare realpath-
+// resolved paths rather than string-building a file:// URL, which breaks on
+// paths containing spaces or non-ASCII, or when reached through a symlink.
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+  } catch {
+    return false;
+  }
+}
+if (isMainModule()) {
+  process.exit(main(process.argv.slice(2)));
+}

package/payload/premium-plugins/sitedesk/plugins/sitedesk-media/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "sitedesk-media",
+  "description": "Turn an operator's raw inputs (a folder or zip of photos, an existing website URL, social-media links, and any notes about the business) into a finished marketing micro-site plus a set of share-ready Open Graph and social tiles. A single-entry orchestrator extracts the brand, asks the operator targeted questions to fill every gap, builds a scrollable single-page site (hero rotator, story, founder section, testimonial, services, FAQ, AEO/JSON-LD), then renders the social tiles with a gallery and captions. Brand-agnostic: all copy and tokens live as placeholders in the templates.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Rubytech LLC"
+  }
+}

package/payload/premium-plugins/sitedesk/plugins/sitedesk-media/PLUGIN.md

@@ -0,0 +1,49 @@
+---
+name: sitedesk-media
+description: "Turn an operator's raw inputs (a folder or zip of photos, an existing website URL, social-media links, and any notes about the business) into a finished marketing micro-site plus a set of share-ready Open Graph and social tiles. A single-entry orchestrator extracts the brand, asks the operator targeted questions to fill every gap, builds a scrollable single-page site (hero rotator, story, founder section, testimonial, services, FAQ, AEO/JSON-LD), then renders the social tiles with a gallery and captions. Brand-agnostic: all copy and tokens live as placeholders in the templates."
+tools: []
+metadata: {"platform":{"optional":true,"embed":["admin"]}}
+---
+
+# SiteDesk — Media
+
+End-to-end marketing-collateral pipeline. From an operator's photos, their
+existing website, social links and any notes, the skills produce a self-contained
+`site/` directory — a scrollable single-page micro-site (`index.html` + `llms.txt`)
+plus a `socials/` folder of Open Graph and social tiles with a gallery and
+captions. The agent extracts the brand, then asks the operator to fill every gap;
+it never invents a fact.
+
+## When to Activate
+
+The operator wants a website and social images for a service business, built from
+mixed source material (photos + a site + social links + notes).
+
+## Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `make-media` | Single-entry orchestrator — intake → ask the gaps → brand-extract → microsite → socials |
+| `brand-extract` | Pull a tokenized palette, logo/icon, and company facts (plus an explicit "still unknown" list) from an existing website |
+| `microsite` | Build the scrollable single-page site from the placeholder template + brand + photos + answers |
+| `socials` | Render exact-size Open Graph + social tiles (PNG) and captions for a named subject — micro-site, job, valuation, or bespoke — with a PII gate for client-data sources; gallery + redaction report; wires og:image for micro-sites |
+
+## Commands
+
+`/make-media <images-dir-or-zip> [website-url] [social-links] [notes…]` — run the full pipeline.
+
+## Tools Used
+
+No MCP server of its own. Skills operate via existing platform tools (Bash, Read,
+Write, Edit, Glob, Grep, WebFetch). Tile rendering uses the on-device `browser`
+plugin (Chrome DevTools Protocol): it sets the viewport and screenshots each tile at
+its exact size against the device's running Chromium — no Playwright ships on a Pi.
+The image encoder for site photos is `cwebp` (libwebp); the browser plugin writes
+tiles as PNG.
+
+## Templates
+
+All copy and colour are placeholders — no client data ships in the templates.
+The token dictionary is in `skills/microsite/references/placeholders.md`; the
+section + image map is in `skills/microsite/references/sections.md`; the operator
+question set is in `skills/make-media/references/intake-and-questions.md`.

package/payload/premium-plugins/sitedesk/plugins/sitedesk-media/README.md

@@ -0,0 +1,70 @@
+# sitedesk-media
+
+Turn an operator's raw inputs — a folder of photos, an existing website, social
+links, and any notes about the business — into a finished marketing **micro-site**
+plus a set of **share-ready social tiles**. The agent extracts the brand, asks the
+operator targeted questions to fill every gap, then builds the site and the social
+collateral. All copy and colour live as placeholders in the templates, so the
+pipeline is brand-agnostic.
+
+## Pipeline
+
+```
+make-media  (orchestrator: intake → ask the gaps → route the steps)
+  ├─ brand-extract   website → palette tokens + logo/icon + company facts (+ gaps)
+  ├─ microsite       templates + brand + photos + answers → site/index.html + llms.txt
+  └─ socials         resolved subject → og/social tiles (PNG) + gallery + captions
+```
+
+Run it with the command:
+
+```
+/make-media <images-dir-or-zip> [website-url] [social-links] [notes…]
+```
+
+or invoke the `make-media` skill directly. Each sub-skill is also usable on its
+own (`brand-extract` for just tokens + logo; `microsite` for just the page;
+`socials` for just the tiles).
+
+## What you get
+
+```
+<output>/site/
+  index.html      llms.txt      favicon.png
+  images/         # curated webp + logo.png + icon.png
+  socials/        # og-{landscape,square,portrait}-{main,interior,build}.png + og-portrait-founder.png
+  socials.html    # tile gallery + OG meta snippet
+  social-posts.md # captions per tile and platform
+  og.html         # tile render page (kept for re-runs)
+<output>/<brand-slug>-microsite.zip
+```
+
+## Principles
+
+- **Ask, never invent.** Every placeholder is a fact about a real business. What
+  the website and the operator's notes don't supply, the agent asks for. A guessed
+  year, phone number, or testimonial is a defect.
+- **Keep claims as claims.** "Trading since 1987" is not an incorporation date;
+  "over 35 years" is not a company age. Company-registration facts come from the
+  register or the operator, never a marketing line.
+- **Verify images by eye, name by convention.** Photos are matched to slots by
+  content (never filename), optimised to webp, and a person is only ever shown in
+  the founder slots and a portrait-only tile.
+- **Plain register for all copy.** No em-dashes, no inflation vocabulary, no
+  AI-marketing cadence. Real testimonials are used verbatim.
+- **Built for answer engines.** The site ships `JSON-LD` (business + FAQ),
+  Open Graph tiles, and an `llms.txt`.
+
+## Templates (all placeholder, no client data)
+
+```
+skills/microsite/templates/index.html     # the single-page site
+skills/microsite/templates/llms.txt
+skills/socials/templates/og.html           # tile render page
+skills/socials/templates/socials.html
+skills/socials/templates/social-posts.md
+```
+
+The full token dictionary is in `skills/microsite/references/placeholders.md`; the
+section + image map is in `skills/microsite/references/sections.md`; the operator
+question set is in `skills/make-media/references/intake-and-questions.md`.

package/payload/premium-plugins/sitedesk/plugins/sitedesk-media/commands/make-media.md

@@ -0,0 +1,13 @@
+---
+description: Build a marketing micro-site + social tiles from an operator's website, photos, social links and notes. Asks questions to fill any gaps.
+argument-hint: <images-dir-or-zip> [website-url] [social-links] [notes…]
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, WebFetch, Skill, AskUserQuestion
+---
+
+Run the `make-media` skill end-to-end on the inputs below.
+
+Inputs: $ARGUMENTS
+
+Follow the orchestrator's routing: `brand-extract` (website + logo + tokens + company facts) → ask the operator the intake questions for every field still missing → `microsite` (build the single-page site into `<output>/site/`) → `socials` in `microsite` mode (render the Open Graph + social tiles, gallery and captions into `<output>/site/socials/`).
+
+Never invent a fact. Where the website and the operator's notes do not supply a value, ask for it before building. Stop at the finished site + social bundle and report the paths.

package/payload/premium-plugins/sitedesk/plugins/sitedesk-media/skills/brand-extract/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: brand-extract
+description: Turn a business's existing website into a brand pack for the micro-site — a tokenized palette (ink/paper/rule/accent plus a deepened accent for legible text), the logo and icon saved as image files, and a brand.md recording the company facts the site exposes (name, contact, services, about copy, socials) together with an explicit list of what is still unknown. Use as the first step of make-media, or on its own when someone wants design tokens + logo + company facts pulled from a URL. Trigger phrases include "extract the brand from <url>", "get tokens and logo from <site>", "pull the company details from their website".
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - WebFetch
+  - Grep
+---
+
+# brand-extract
+
+Reads an existing website and produces what the `microsite` and `socials`
+templates need to be branded: a **palette**, the **logo** and **icon** as files,
+and a **brand.md** of company facts with an honest "still unknown" list.
+
+## Outputs
+
+```
+<output>/site/images/logo.png      # the wordmark/lockup, on a white or transparent ground
+<output>/site/images/icon.png      # the square mark / monogram (favicon source)
+<output>/site/favicon.png          # 64px icon
+<output>/brand.md                  # tokens + facts found + gaps
+```
+
+## Palette — the token contract
+
+The templates resolve every colour through ten CSS custom properties. Fill their
+values from the site; do not introduce new token names.
+
+| Token | Role | How to choose |
+|---|---|---|
+| `INK_900` | primary text, headings, dark surfaces | the site's darkest near-black text colour |
+| `INK_700` | secondary text | a step lighter than INK_900 |
+| `INK_400` | muted / captions | a mid grey |
+| `PAPER_100` | white surface | the lightest surface (usually `#FFFFFF`) |
+| `PAPER_200` | page-bg tint / bands | a faint off-white for alternating bands |
+| `RULE_100` | borders / dividers | a pale neutral hairline |
+| `ACCENT` | the brand accent (separators, hairlines, CTA hover) | the logo's accent colour, used verbatim |
+| `ACCENT_TEXT` | accent used as small text (eyebrows, links) | the accent **deepened** until it is legible at ~10px on white (aim for ≥ 3:1 contrast). This is the one token you compute rather than copy — a light brand accent is unreadable as tracked-caps text, so darken it while keeping the same hue. |
+| `ACCENT_SOFT` | soft tint behind accent text | a pale wash of the accent |
+| `BRAND_GREY` | logo/wordmark grey | the logo's neutral grey |
+
+If the operator supplied design tokens directly, use them verbatim and skip
+derivation. The three-font editorial system (Cormorant Garamond display, Lora
+body, Inter UI) is the template default and stays unless the operator asks to
+change it — brand identity lives in the logo, the accent, and the copy.
+
+## Logo — make it usable on dark and light
+
+Save the site's primary logo as `images/logo.png`. Note its background: a logo on
+a **white ground** sits cleanly on a light nav but cannot be dropped onto a dark
+photo. The `socials` tiles place the logo on a white chip precisely so a
+white-ground logo still reads over any hero. Record in brand.md whether a
+transparent or light-art variant exists. Save the square mark as `images/icon.png`
+and a 64px `favicon.png`.
+
+Right-size the logo (a multi-megabyte original is overkill for a 42–84px display);
+keep it crisp but reasonable.
+
+## Facts — record, and mark the gaps
+
+Write `brand.md` with everything the site exposes: trading name, legal name,
+tagline, sector, established year, phone, email, address, region, services,
+"about" copy, social links. For every field the site does **not** expose, write
+it under a `## Still unknown` heading. That list is exactly what `make-media`
+turns into questions for the operator.
+
+Do not promote a marketing line to a hard fact. "Over 35 years" is a claim about
+experience, not a company age; "since 1987" is a trading date, not necessarily an
+incorporation date. Keep claims as claims.
+
+## The 2000px image rule
+
+Never `Read` an image whose longest edge exceeds 2000px — it can break the
+session. Measure first (`sips -g pixelWidth -g pixelHeight`), and if larger,
+downscale a preview into `/tmp`, read that, and delete it.
+
+## Completion criteria
+
+- `images/logo.png`, `images/icon.png`, `favicon.png` exist and are right-sized.
+- `brand.md` lists the ten palette tokens with values, the company facts found,
+  and an explicit "Still unknown" list.
+- No colour was invented beyond deriving `ACCENT_TEXT` from `ACCENT`; no marketing
+  claim was recorded as a registration fact.