Add portable Density guidance source

README.md

@@ -71,7 +71,17 @@ The first managed runtime asset is published for `darwin-arm64`. Other platforms
 
 The default setup path prepares a 30-day recent local preload for all locations and can continue the remaining supported local history in a background job. Agents should use `onboarding_status` to track that job and tell the user when the full supported local history is ready. For explicit separate customer-owned history exports, use `historical_export`; the plugin should not treat the recent preload as a limit on local data access.
 
-The plugin ships one visual design contract at `plugins/density/assets/design.md`. Edit that file when a customer-specific artifact style is needed.
+## Guidance Source
+
+The plugin keeps portable product guidance in `plugins/density/guidance/`.
+
+Codex still loads the packaged skill files from `plugins/density/skills/*/SKILL.md` and the visual contract from `plugins/density/assets/design.md`. Keep those packaged files mirrored from the shared guidance source; the packaging tests fail when they drift.
+
+Use this split to keep Codex polished while leaving the guidance easy to package for other hosts later. Platform-specific files such as `skills/*/agents/openai.yaml` stay in the Codex skill folders.
+
+The plugin ships one visual design contract at `plugins/density/assets/design.md`, mirrored from `plugins/density/guidance/design.md`. Edit the guidance source and packaged asset together when a customer-specific artifact style is needed.
+
+After changing skill text or plugin packaging, reinstall/update the plugin and start a new Codex thread so the latest skills load. CLI/runtime-only changes can be tested immediately when the managed runtime is pointed at a local dev CLI.
 
 ## Marketplace Layout
 

plugins/density/guidance/design.md

@@ -0,0 +1,90 @@
+# Density Artifact Design
+
+Use this file as the single visual contract for Density plugin artifacts. If a user wants customer-specific branding, edit this file instead of adding a second competing style guide.
+
+## Principles
+
+- The default aesthetic is Broadsheet/Tufte: concise analytical brief, high signal-to-ink ratio, direct claims, restrained rules, and no generic dashboard chrome.
+- Lead with the answer, then show the evidence.
+- Make every important number comparative. Show the measured value with the denominator or baseline that makes it interpretable, then add the nearest internal comparison and a named Density benchmark when available.
+- Define analytical terms where the reader sees them. Put working day, business hours, local time, utilization, time used, saturation, and availability definitions in subtitles, labels, legends, or notes instead of relying on chat context.
+- Prefer calm analytical briefs over generic dashboards.
+- Make floorplans, charts, tables, caveats, and provenance feel like one system.
+- Keep visuals useful when exported, screenshotted, or read without the chat context.
+- Never hide data-quality caveats behind decorative design.
+
+## Default Look
+
+- Background: warm off-white or white.
+- Text: dark neutral, high contrast.
+- Accent: Density rust `#8c2f1d` for the primary finding.
+- Secondary colors: restrained neutrals, muted teal, and muted blue for comparisons or availability states.
+- Typography: large serif titles for report pages; compact sans-serif labels and table text for dense analytical surfaces. Chart titles should read like a sentence-case claim, not a dashboard widget label.
+- Radius: 8px or less for cards, controls, and repeated items.
+- Avoid decorative gradients, floating blobs, heavy shadows, and marketing-style hero layouts.
+- Avoid chart-card styling when the artifact itself is the answer. The chart should feel like a page or brief, not a screenshot of a dashboard tile.
+
+## Charts
+
+- Show a visible source badge: `Local`, `Live`, `Benchmark`, or `Mixed`.
+- `Local` means customer-owned historical data from local Parquet/DuckDB.
+- `Live` means current availability or presence from the authenticated live feed.
+- `Benchmark` means display-safe Density benchmark-network context.
+- `Mixed` means the artifact combines more than one source layer; label each part clearly.
+- Use direct labels when practical.
+- Use legends only when direct labels would clutter the chart.
+- Legends, badges, subtitles, and labels must never overlap the title, marks, axes, or each other. Prefer direct labels or a below-chart legend when the title is long.
+- Sort ranked charts by the metric being discussed.
+- Show units in labels or subtitles, such as hours per day, person-hours, percent of working hours, or spaces.
+- Analyze only available measured spaces for normal utilization charts. Planning, inactive, retired, decommissioned, and unavailable spaces are eligibility inputs, not commentary, unless the chart is explicitly about data health, setup, lifecycle coverage, or missing inventory.
+- Avoid naked stats in titles, labels, and callouts. Match the denominator to the question: for one room over time, use language like "busy for 12% of working hours"; for hour-of-day charts across rooms, use "at 2pm, 13% of available measured rooms were occupied" instead of room-hour language.
+- Use the accent color only for the lead series or important highlight.
+- Keep comparison series muted.
+- Include the time window, business-hours assumption with definition, timezone basis, and data freshness when relevant.
+- Keep chart generation dependency-light but not layout-blind. If rendering by hand, reserve explicit title, subtitle, legend, plot, and footnote regions before drawing marks.
+- Prefer generated chart artifacts from the Density CLI or plugin chart contract over ad hoc one-off scripts. If a one-off fallback is unavoidable, it must still follow this design file and be visually inspected for collisions.
+
+## Atlas Analytics Defaults
+
+- Treat Atlas as the baseline product grammar for local analytics.
+- Show effective scope when it affects interpretation: org, building/floor, timezone, date window, operating hours, working days, and interval.
+- Default utilization charts to local Atlas operating hours, typically `8am-6pm`, unless the artifact says otherwise.
+- Use local timezone projections from Atlas-style views for hour, weekday, heatmap, and working-hours displays.
+- Never label a UTC-grouped chart as local business-hour analysis.
+- Prefer top/bottom 12 ranked bars for room, booth, and capacity findings.
+- Use gray for no data, a separate neutral for zero observed use, and an explicit caveat for low uptime or unhealthy signals.
+- For saturation/runout visuals, write the threshold in the subtitle or legend.
+
+## Floorplans
+
+- Preserve the user's ability to read the base floorplan.
+- Use overlays for the analytical signal, not for decoration.
+- Use a clear status palette:
+  - available: muted green or teal
+  - occupied or most-used: Density rust
+  - unavailable, stale, or unhealthy: muted gray
+  - missing data: light neutral with explicit label or legend entry
+- For historical utilization, use rank, intensity, or labels rather than live availability wording.
+- For real-time wayfinding, use current availability wording and avoid implying a historical trend.
+
+## Tables And Lists
+
+- Put ranked findings in a compact table or list near the visualization.
+- Include space name, space type, capacity when known, metric value, comparison value, delta or ratio, and data-quality note when needed.
+- Keep numbers rounded enough to scan, but not so rounded that rankings become misleading.
+
+## Caveats And Provenance
+
+Every analytical artifact should make these visible when they matter:
+
+- customer or org scope
+- building, floor, or space scope
+- date range
+- business-hours window, including timezone and weekday/all-day basis
+- local data freshness
+- whether the answer used local Parquet/DuckDB, live APIs, or benchmark APIs
+- missing, stale, or filtered data
+
+## Modification Contract
+
+Users may modify this file to match customer branding. Keep the file name and role stable so all Density skills continue to share one visual source of truth.

plugins/density/guidance/skills/benchmarking.md

@@ -0,0 +1,50 @@
+---
+name: benchmarking
+description: Use when the user asks how a Density customer, building, floor, room type, workplace pattern, or utilization result compares against peer benchmarks or target ranges.
+---
+
+# Density Benchmarking
+
+Use this skill for benchmark scorecards, peer comparisons, target ranges, and portfolio-level interpretation.
+
+Always use `../../assets/design.md` for visual artifacts.
+
+## Interaction Contract
+
+- Lead with the practical workplace answer, then the source, freshness, confidence, and caveat needed to trust it.
+- Keep CLI, MCP, shell, cache, and tool-routing mechanics out of user-facing prose unless the user asks, an action is blocked, or those mechanics change the next step.
+- Ask one crisp clarifying question when building, floor, space type, time window, or current-versus-historical scope is ambiguous.
+- Keep local historical data, live availability, benchmark context, and sensor health separate.
+- Prefer human-readable names and labels. Avoid raw ids unless the user asks or debugging requires them.
+- Define operational terms in place when they affect the comparison, especially working day, business hours, local time, utilization, time used, saturation, and availability.
+
+## Progress Update Contract
+
+Keep user-visible progress updates at the workplace level:
+
+- Say what decision you are making for the user, not which skill, MCP tool, CLI command, cache path, SQL query, or local file is being used.
+- Do not mention parser misses, reserved SQL words, DuckDB internals, shell commands, skill loading, or tool routing unless the user explicitly asks for debugging.
+- If a query misroutes or needs a retry, recover quietly and disclose only the resulting source, scope, freshness, confidence, or caveat needed to trust the final answer.
+- Good updates sound like: "I am checking the local historical window and office scope" or "I am using complete local business days (weekdays within the stated local working-hours window) so a partial day does not understate utilization."
+
+Read `references/darshan-benchmark-methodology.md` before answering benchmark math, scorecard, peer comparison, or recommendation questions.
+
+## Rules
+
+- Do not invent benchmark thresholds.
+- Use `benchmark_compare` when available.
+- Prefer Darshan's benchmark scorecard methodology where available.
+- Treat every benchmark answer as comparative by construction: measured customer value, nearest internal customer comparison, then the approved Density benchmark segment when available.
+- Name the benchmark segment specifically, such as room-size bucket, space function, floor type, capacity bucket, region, or workplace cohort returned by the benchmark source. Avoid generic phrases like "broader benchmark" when a specific segment is available.
+- Use numbers and percentages together when they improve comprehension: measured value, denominator or baseline, delta, ratio, percentile, sample size, and reliability.
+- Include the benchmark time basis when available, such as "per working day (8am-6pm local time)" or "during business hours (defined by the building settings)." If the benchmark source does not expose the basis, say that the time-basis comparison is unavailable.
+- Keep raw peer distributions server-side or inside the benchmark API contract.
+- Return display-safe benchmark findings, not raw customer peer rows.
+- Separate findings from recommendations.
+- State when sample size or data quality makes a benchmark unreliable.
+- If no approved benchmark source is connected, say that benchmark context is unavailable instead of deriving peer context from local customer Parquet.
+- Never describe Density benchmark context as another customer's data. It is generalized, approved comparative intelligence only.
+
+## Data Routing
+
+Use local Parquet/DuckDB for the customer's historical metrics. Use benchmark APIs or approved benchmark snapshots for peer context.

plugins/density/guidance/skills/data-health.md

@@ -0,0 +1,64 @@
+---
+name: data-health
+description: Use when the user asks why Density local data is missing, stale, zero, inconsistent with Atlas, too slow, or not suitable for local Parquet/DuckDB analytics.
+---
+
+# Density Data Health
+
+Use this skill for local Parquet/DuckDB readiness, freshness, zero-data diagnosis, sync gaps, and repair guidance.
+
+## Interaction Contract
+
+- Lead with the practical workplace answer, then the source, freshness, confidence, and caveat needed to trust it.
+- Keep CLI, MCP, shell, cache, and tool-routing mechanics out of user-facing prose unless the user asks, an action is blocked, or those mechanics change the next step.
+- Ask one crisp clarifying question when building, floor, space type, time window, or current-versus-historical scope is ambiguous.
+- Keep local historical data, live availability, benchmark context, and sensor health separate.
+- Prefer human-readable names and labels. Avoid raw ids unless the user asks or debugging requires them.
+
+## Progress Update Contract
+
+Keep user-visible progress updates at the workplace level:
+
+- Say what decision you are making for the user, not which skill, MCP tool, CLI command, cache path, SQL query, or local file is being used.
+- Do not mention parser misses, reserved SQL words, DuckDB internals, shell commands, skill loading, or tool routing unless the user explicitly asks for debugging.
+- If a query misroutes or needs a retry, recover quietly and disclose only the resulting source, scope, freshness, confidence, or caveat needed to trust the final answer.
+- Good updates sound like: "I am checking the local historical window and office scope" or "I am using complete local business days (weekdays within the stated local working-hours window) so a partial day does not understate utilization."
+
+Prefer the plugin MCP tools when available:
+
+- `setup`
+- `local_data_profile`
+- `data_health_report`
+- `storage_report`
+- `starter_questions`
+- `repair_fast_questions`
+- `onboard_customer`
+- `onboarding_status`
+- `historical_export`
+
+## Diagnosis Checklist
+
+Check these before answering an analytical question from local data:
+
+- canonical Parquet tables exist
+- normalized fast-question tables exist
+- local metrics cover the requested time window
+- timestamps overlap the user's requested date range
+- space metadata joins to metrics
+- space type filters match the product taxonomy
+- parent/child hierarchy is handled correctly
+- uptime or health filters are not removing everything
+- starter answers include nonzero useful results when applicable
+
+## Response Rule
+
+When data is not good enough, say exactly what is missing and what evidence showed that. Then give one primary next action: repair metadata, sync metrics, export Parquet, warm starter questions, or narrow the question.
+
+If the issue is that the requested window is broader than the recent preload, check `onboarding_status` first. If a background deeper-history job is still running, say the local dataset is recent-first and still filling in deeper history. If no job exists, recommend the deeper-history onboarding/export path rather than implying the local-first product is capped at the preload window.
+
+## Recovery Rules
+
+Treat sync state as diagnostic evidence, not as user-facing detail by default.
+When debugging local data freshness or sync gaps, use `state.json` as the source of truth for cursors, `updatedSince`, `lastSyncAt`, and rows synced.
+Prefer deterministic recovery: retry with the same cursor first, and rebuild only as an explicit fallback.
+Use incomplete recent data only for deliberate diagnostics; do not quietly use it for normal utilization answers.