@event4u/agent-config 5.4.0 → 5.5.0

package/docs/contracts/skill-discovery.md

@@ -0,0 +1,80 @@
+---
+stability: experimental
+---
+
+# Skill Discovery Contract
+
+> **Status** · v0 / design · 2026-05-30. Phase 3 of `road-to-leaner-core-and-discovery`.
+> **Local-only.** Mirrors [`local-analytics.md`](local-analytics.md): no network egress, no POST,
+> no remote Worker. The recommender reads local files only and honours the analytics opt-out.
+
+## Problem
+
+The package ships 220 skills. Both council members named "218-skill paralysis" as the dominant
+discoverability risk. This contract defines a **recommendation surface** that turns existing signals
+into a short, *explained* shortlist — and explicitly **reuses** signals already on disk. It adds **no**
+new always-loaded layer (that would fail the Phase-1 leaner-core premise).
+
+## Input signals (all local, all already on disk)
+
+| Signal | Source | Used for |
+|---|---|---|
+| Skill catalog | `.agent-src/skills/*/SKILL.md` frontmatter (`name`, `description`, `domain`) | candidate universe + `domain` category |
+| Role shortlist | `agents/roles/<role>/skills.yml` (priority-ordered `id` + `why`) | `most-useful-for-role` |
+| Local analytics | `~/.event4u/agent-config/workspace/analytics/events.jsonl` (`event`, `data.role`, `data.task`, optional `data.skill`) | `recently-adopted`, `popular-in-role` |
+
+The role `skills.yml` is the strongest signal and is always present; analytics is optional and
+degrades gracefully (below).
+
+## Four recommendation classes
+
+| Class | Ranking basis | `why` shape |
+|---|---|---|
+| `most-useful-for-role` | role `skills.yml` priority order | the shortlist's own `why:` line |
+| `related-to-current-task` | skills sharing the `domain` of the role's shortlist skills, not already shortlisted | `same domain (<domain>) as your role's core skills` |
+| `recently-adopted` | analytics events in the last 14 days carrying a skill id (`data.skill`), most-recent first | `used <N>d ago in this workspace` |
+| `popular-in-role` | analytics skill-events filtered by `data.role`, by frequency | `launched <N>× by the <role> role locally` |
+
+## Explanation requirement — non-negotiable
+
+```
+EVERY RECOMMENDATION CARRIES A NON-EMPTY `why`. NEVER AN UNEXPLAINED SCORE.
+```
+
+Both council members flagged "opaque / self-referential recommendations without real usage signal" as
+the main risk. A result with no `why` is a contract violation. The `why` names the *signal* (role match,
+domain adjacency, recent-adoption, role-popularity) — never a bare number.
+
+## Graceful degradation — analytics absent or opted out
+
+Analytics is optional. When the JSONL file is missing, empty, or the opt-out is set
+(`AGENT_CONFIG_NO_LOCAL_ANALYTICS` env or `analytics.local: off` config — same checks as
+`local-analytics.md`), the two analytics-backed classes do not fabricate signal:
+
+- `recently-adopted` and `popular-in-role` fall back to **role-shortlist order** with an honest `why`
+  (`from your role shortlist — no local usage signal yet`).
+- `most-useful-for-role` and `related-to-current-task` are unaffected (catalog + role only).
+
+The recommender therefore always returns a useful, explained list — even on a fresh machine with no
+analytics history. Today's analytics schema logs `data.task` (not skill ids); the skill-level classes
+read the forward-compatible `data.skill` field and degrade to the role-shortlist fallback until it is
+populated. No class ever returns an empty `why`.
+
+## Local-only / no-network floor
+
+The recommender opens local files only. It performs no network I/O, writes nothing, and never emits a
+prompt or response body. It is read-only over the catalog, the role file, and (if present) the analytics
+log. This mirrors `local-analytics.md` and does not lift the 3.1.0 Hard-Floor.
+
+## Surfaces
+
+- CLI / agent: `/skills:discover [role]` → Markdown table (`skill · class · why · first command`).
+  Defaults to the active role experience when one is set; otherwise prompts for a role.
+- GUI: a right-rail "Suggested skills" strip on the Workspace tab, reusing the `/api/v1/workspace/*`
+  bridge (no new infra). Deferrable behind the CLI surface if the employee-roadmap right-rail blocker
+  is still open.
+
+## Implementation
+
+`scripts/skill_discovery.py` (≤ 300 LOC). Pure-local, no POST. Honours the analytics opt-out env + config.
+Coverage: `tests/test_skill_discovery.py` against a fixture catalog + fixture analytics JSONL.

package/docs/contracts/skill-dry-run.md

@@ -0,0 +1,47 @@
+---
+stability: experimental
+---
+
+# Skill Dry-Run / Preview Contract
+
+> **Status** · v0 / design · 2026-05-30. Phase 5 of `road-to-leaner-core-and-discovery`.
+> The council's missing-item catch: with 220 skills, non-dev personas need a non-destructive way
+> to see what a skill/command will do **before** running it.
+
+## What "preview" means
+
+A preview reads a skill's **declared intent** — its frontmatter and `## Steps` body — and renders a
+plain-language "this skill will…" summary. It surfaces:
+
+- the skill's **declared steps** (the `## Steps` section headings);
+- its **execution type** (`manual` / `assisted` / `automated`, default `manual`) and **handler**
+  (`none` / `shell` / `php` / `node` / `internal`);
+- its declared **`allowed_tools`**;
+- any **file or command targets** named in the body (backtick paths, `python3 scripts/…` invocations).
+
+## Explicit non-goals
+
+```
+PREVIEW IS NOT A SANDBOX. IT DOES NOT EXECUTE A FENCED COPY OF THE SKILL.
+IT IS NOT A GUARANTEE OF SIDE-EFFECT-FREENESS FOR SKILLS WITH AN `execution` BLOCK.
+```
+
+Preview reads declared intent — it does not run the skill, does not dry-run its commands, and cannot
+prove a skill is harmless. It tells you what the skill *says* it will touch, so you can decide whether
+to run it. For `execution: manual` skills (the default), it states plainly: **instructional only — no
+automatic execution** (per [`runtime-safety`](../../.agent-src/rules/runtime-safety.md): `manual` is
+instructional, `assisted` must propose before executing).
+
+## Surface
+
+- CLI / agent: `/skill:preview <name>` — plain-language summary by default; `--technical` shows the raw
+  frontmatter + step list.
+- Script: `scripts/skill_preview.py <name> [--technical] [--format text|json]`.
+
+Plain-language mode reuses the plain-explain tone (employee-roadmap Phase 6). A malformed or missing
+SKILL.md degrades to a **structured error**, never a crash.
+
+## Implementation
+
+`scripts/skill_preview.py` (≤ 250 LOC). Read-only over `.agent-src/skills/<name>/SKILL.md`. No network,
+no execution. Coverage: `tests/test_skill_preview.py`.

package/docs/decisions/ADR-032-linked-projects-scope.md

@@ -99,9 +99,13 @@ telemetry.
 
 ## Open follow-ups
 
-- **Consumer detector reachability:** the detector lives in `scripts/_lib/`;
-  exposing it as an `agent-config` CLI subcommand for consumer installs is a
-  follow-up. Import-reachable in this repo / co-located maintainer setups today.
+- **Consumer detector reachability:** ✅ **Closed (2026-05-30, `road-to-leaner-core-and-discovery`
+  Phase 4).** The detector is now exposed as `agent-config linked-projects:list`
+  (`scripts/linked_projects_list.py`, registered in `src/cli/registry.ts` + `scripts/_dispatch.bash`),
+  wrapping `scripts/_lib/linked_projects.detect_linked_projects` + the `.agent-settings.local.yml`
+  opt-in cascade. Cross-repo *retrieval* over the opted-in siblings ships alongside it
+  (`/knowledge:cross-repo`, `scripts/cross_repo_retrieve.py`) per
+  [`cross-repo-retrieval`](../contracts/cross-repo-retrieval.md).
 - **Multi-agent verification:** only Claude Code was empirically validated.
   Cursor / Augment / Copilot are unverified — the guide's manual snippet covers
   them until an interactive per-IDE test is run.

package/docs/getting-started.md

@@ -169,7 +169,7 @@ Your agent now understands slash commands:
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
 
-→ [Browse all 135 active commands](../.agent-src/commands/)
+→ [Browse all 141 active commands](../.agent-src/commands/)
 
 ---
 

package/docs/guides/cross-repo-linked-projects.md

@@ -77,6 +77,13 @@ If it reports the name, cross-repo access works. An out-of-root edit will prompt
 for confirmation, then succeed — that is expected (the agent's permission gate
 still applies).
 
+## Next: pull context from a sibling
+
+Detection makes the agent *aware* of a sibling. To have it **read** targeted
+context from one — a shared type, an API contract, a config — without copying
+the sibling's files in, see [Cross-repo retrieval](cross-repo-retrieval.md)
+(`agent-config linked-projects:list` + `/knowledge:cross-repo`).
+
 ## Tell us what works
 
 Auto-detection is verified for Claude Code only. If you use Cursor, Augment, or

package/docs/guides/cross-repo-retrieval.md

@@ -0,0 +1,61 @@
+# Cross-repo retrieval — pull sibling context without copying files
+
+Once the agent knows about a sibling repo ([detection guide](cross-repo-linked-projects.md)),
+cross-repo retrieval lets it **read targeted context** from that sibling — a shared type, an
+API contract the frontend consumes, a config the sibling owns — without bulk-including the
+sibling's files. It is the read layer on top of detection.
+
+It stays inside [ADR-032](../decisions/ADR-032-linked-projects-scope.md) Option A: read-only,
+opt-in per sibling, targeted query only. No full-tree sweep, no implicit inclusion, no writes.
+
+## 1. See which siblings are reachable
+
+```
+agent-config linked-projects:list
+```
+
+Prints the opted-in siblings as `path · detected via · large`. Add `--all` to see detected
+siblings you have not decided on yet. A sibling only becomes reachable once you set
+`include: true` for it in `agents/settings/.agent-settings.local.yml` (see the detection guide).
+
+## 2. Retrieve targeted context
+
+```
+/knowledge:cross-repo "OrderApiContract"
+```
+
+Under the hood:
+
+```bash
+python3 scripts/cross_repo_retrieve.py "OrderApiContract" [--path-scope 'src/*.ts'] [--max-chunks 8]
+```
+
+You get a bounded table — `source_repo · path · freshness · why` — drawn only from opted-in
+siblings. Each chunk is redacted (secrets and PII are scrubbed before anything is shown), so
+no credential ever crosses a repo boundary.
+
+## 3. Scope large siblings
+
+A sibling flagged `large` by the detector **requires** a `--path-scope` glob:
+
+```
+/knowledge:cross-repo "config" --path-scope 'packages/shared/**'
+```
+
+Without a scope, a large sibling is skipped with a note — this keeps retrieval cheap and
+targeted instead of walking a huge tree.
+
+## How it ranks in memory
+
+When a skill retrieves memory with the `cross-repo` type, matches are tagged `source: cross-repo`
+and scored **below** the project's own curated knowledge — so cross-repo context informs the
+answer but never outranks your own repo's truth.
+
+## Notes
+
+- **Read-only.** The surface never writes to a sibling. Out-of-root writes still pass the host
+  permission gate; cross-repo retrieval writes nothing.
+- **Opt-in only.** A sibling that is not `include: true` is never read.
+- **Targeted only.** Path-glob + content grep, never a blind full walk.
+- Contract: [`cross-repo-retrieval`](../contracts/cross-repo-retrieval.md). Detection story:
+  [`cross-repo-linked-projects`](cross-repo-linked-projects.md).

package/docs/guides/skill-discovery.md

@@ -0,0 +1,71 @@
+# Skill discovery — a 3-minute walkthrough
+
+The package ships 220 skills. You do not need to know them. `/skills:discover`
+turns the catalog into a short, **explained** shortlist for your role — every
+row tells you *why* it is suggested, so you never adopt a skill on faith.
+
+It is local-only: it reads the skill catalog, your role's shortlist, and (if
+present) your local-analytics log. No network, no writes.
+
+## 1. Run it for your role
+
+```
+/skills:discover sales
+```
+
+Or, with a role experience already active, just `/skills:discover` — it picks
+up `roles.active_role` from `.agent-settings.yml`.
+
+Under the hood the command runs:
+
+```bash
+python3 scripts/skill_discovery.py --role sales
+```
+
+## 2. Read the `why` column
+
+The output is a table. The third column is the point — it names the **signal**
+behind each suggestion, never a bare score:
+
+```
+| skill                  | class                   | why                                                       | first command            |
+|------------------------|-------------------------|-----------------------------------------------------------|---------------------------|
+| refine-prompt          | most-useful-for-role    | Tightens fuzzy buyer briefs before drafting               | Skill › refine-prompt     |
+| voice-and-tone-design  | most-useful-for-role    | Locks the deal voice across customer + procurement        | Skill › voice-and-tone-design |
+| competitive-positioning| most-useful-for-role    | Surfaces the ours-vs-theirs delta when a competitor named | Skill › competitive-positioning |
+| activation-design      | related-to-current-task | same domain (product) as your sales core skills           | Skill › activation-design |
+| customer-research      | recently-adopted        | from your role shortlist — no local usage signal yet      | Skill › customer-research |
+| funnel-analysis        | popular-in-role         | from your role shortlist — no local usage signal yet      | Skill › funnel-analysis   |
+```
+
+The four classes:
+
+- **most-useful-for-role** — your role's curated priority shortlist.
+- **related-to-current-task** — same-domain peers you have not shortlisted yet.
+- **recently-adopted** — what you actually used recently (from local analytics);
+  on a fresh machine with no usage history it honestly says *"no local usage
+  signal yet"* and falls back to your shortlist instead of inventing a number.
+- **popular-in-role** — what your role launches most locally (same fallback).
+
+## 3. Adopt one
+
+Pick a row, read its `why`, and start with the `first command`. Unsure what a
+skill will actually do before you commit? Preview it first:
+
+```
+/skill:preview competitive-positioning
+```
+
+That is the safe adoption loop: **discover → preview → run**.
+
+## Notes
+
+- **Local-only.** `/skills:discover` never touches the network and writes
+  nothing. It reads the catalog, your role file, and the optional analytics log.
+- **Analytics is optional.** Opt out with `AGENT_CONFIG_NO_LOCAL_ANALYTICS=1`
+  or `analytics.local: off` in `.agent-settings.yml`. The two usage-driven
+  classes then fall back to your role shortlist — the list is still useful, just
+  without the personalised signal.
+- **`--format json`** emits the same data machine-readably; **`--limit N`** sets
+  how many results per class (default 5).
+- Contract: [`skill-discovery`](../contracts/skill-discovery.md).

package/docs/guides/skill-preview.md

@@ -0,0 +1,71 @@
+# Skill preview — see what a skill does before you run it
+
+With 220 skills and some that run commands, you should not have to run a skill to
+find out what it touches. `/skill:preview` reads a skill's **declared intent** —
+its steps, execution type, tools, and any file/command targets — and renders a
+plain-language summary. Read-only: it never runs the skill.
+
+This is the middle of the safe adoption loop: **discover → preview → run**.
+
+## 1. Discover, then preview
+
+Find a candidate with [`/skills:discover`](skill-discovery.md), then look before you leap:
+
+```
+/skill:preview competitive-positioning
+```
+
+Under the hood:
+
+```bash
+python3 scripts/skill_preview.py competitive-positioning
+```
+
+## 2. Read the summary
+
+A **manual** skill (the default) is pure guidance — preview says so plainly:
+
+```
+# Preview — `accessibility-auditor`
+
+**Execution: instructional only.** This skill does not run anything automatically —
+it guides the agent step by step.
+
+_No tools, commands, or file targets declared — pure guidance._
+```
+
+An **assisted** skill proposes actions you approve — preview surfaces the command
+and tools it declares:
+
+```
+# Preview — `adr-create`
+
+**Execution: assisted** (handler `shell`). It will *propose* actions for you to
+approve — it never executes silently.
+
+This skill will walk these steps:
+- Pick the next ADR number
+- Write the standard template
+- Regenerate the index
+
+Declared command: `python3 scripts/adr/regenerate_index.py`
+```
+
+Add `--technical` for the raw frontmatter + numbered step list.
+
+## 3. Decide, then run
+
+Preview hands the decision back to you. If the declared steps and targets look
+right, invoke the skill. If not, skip it — you have spent zero side effects
+finding out.
+
+## What preview is not
+
+- **Not a sandbox.** It does not run the skill or a fenced copy of it.
+- **Not a safety guarantee.** It shows what the skill *declares* it will touch —
+  it cannot prove a skill with an `execution` block is side-effect-free.
+
+A malformed or missing skill yields a structured error, never a crash.
+
+Contract: [`skill-dry-run`](../contracts/skill-dry-run.md). Pairs with
+[`skill-discovery`](skill-discovery.md) as the discover → preview → run loop.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "5.4.0",
+    "version": "5.5.0",
     "description": "Universal AI Agent OS \u2014 audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,

package/scripts/_dispatch.bash

@@ -165,6 +165,8 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                                     --payload <path|event-name> [--native-event <native>]
                                     [--manifest <path>] [--json] [--dry-run]
   memory:lookup              Retrieve memory entries (text or JSON envelope)
+  linked-projects:list       List opted-in IDE-attached sibling repos (path · detected_via · large)
+                             Flags: --all (show undecided too), --format json
   memory:signal              Append a provisional intake signal (memory proposal)
   memory:hash                Hash a memory entry (YAML or JSON stdin)
   memory:check               Validate memory YAML schema + staleness
@@ -419,6 +421,13 @@ cmd_memory_lookup() {
   exec python3 "$script" "$@"
 }
 
+cmd_linked_projects_list() {
+  require_python3
+  local script
+  script="$(resolve_script "scripts/linked_projects_list.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
 cmd_memory_signal() {
   require_python3
   local script
@@ -928,6 +937,7 @@ main() {
     implement-ticket)        cmd_implement_ticket "$@" ;;
     work)                    cmd_work "$@" ;;
     memory:lookup)           cmd_memory_lookup "$@" ;;
+    linked-projects:list)    cmd_linked_projects_list "$@" ;;
     memory:signal)           cmd_memory_signal "$@" ;;
     memory:hash)             cmd_memory_hash "$@" ;;
     memory:check)            cmd_memory_check "$@" ;;

package/scripts/ai-video/lib/probe-audio.sh

@@ -0,0 +1,181 @@
+#!/usr/bin/env bash
+# probe-audio.sh — turn a song file into a deterministic, network-free
+# JSON summary the `song-to-script` skill maps to scenes:
+#
+#   {"duration": <seconds>,
+#    "method": "silence" | "rms" | "interval",
+#    "warning": "<present only for the interval fallback>",
+#    "sections": [{"start":0.0,"end":12.5,"energy":0.41,"label":"intro"}, ...]}
+#
+# HONEST FRAMING (AI-council design review, 2026-05-30): this is energy /
+# silence segmentation, NOT beat detection or musical analysis. Modern
+# masters are brick-walled (near-constant RMS), so a real cut structure
+# is often absent. The probe therefore degrades through three methods and
+# always reports which one produced the anchors:
+#
+#   1. silence  — ffmpeg silencedetect found real quiet gaps → true cuts.
+#   2. rms      — no usable silence; greedy-merge per-window RMS energy.
+#   3. interval — track is structurally flat (brick-walled / sustained):
+#                 fall back to fixed-interval cuts and SET `warning` so the
+#                 caller (and the operator) knows timing is not musical.
+#
+# Sections are cut anchors, never a transcription. For beat-accurate cuts
+# the operator passes `--scene-durations` to /video:from-song instead.
+#
+# Usage:
+#   probe-audio.sh <song-file> [--window <seconds>] [--interval <seconds>]
+#                              [--silence-db <dB>] [--silence-min <seconds>]
+#
+#   --window       RMS analysis window (default 3)
+#   --interval     fixed-interval fallback section length (default 15)
+#   --silence-db   silencedetect noise floor (default -30)
+#   --silence-min  silencedetect minimum gap to count as a boundary (default 0.5)
+#
+# Exit codes:
+#   0  JSON written to stdout
+#   2  usage / file missing
+#   3  required tool missing (ffprobe / ffmpeg)
+#   4  no audio stream in the file
+
+set -euo pipefail
+
+die() { printf 'probe-audio: %s\n' "$2" >&2; exit "$1"; }
+
+[ "$#" -ge 1 ] || die 2 "usage: $0 <song-file> [--window <s>] [--interval <s>] [--silence-db <dB>] [--silence-min <s>]"
+
+song="$1"; shift || true
+window=3
+interval=15
+silence_db=-30
+silence_min=0.5
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --window)      window="${2:-3}";       shift 2 ;;
+    --interval)    interval="${2:-15}";     shift 2 ;;
+    --silence-db)  silence_db="${2:--30}";  shift 2 ;;
+    --silence-min) silence_min="${2:-0.5}"; shift 2 ;;
+    *) die 2 "unknown arg: $1" ;;
+  esac
+done
+
+[ -f "${song}" ] || die 2 "file not found: ${song}"
+command -v ffprobe >/dev/null 2>&1 || die 3 "ffprobe not found"
+command -v ffmpeg  >/dev/null 2>&1 || die 3 "ffmpeg not found"
+
+# --- 1. duration + audio-stream check ----------------------------------
+duration="$(ffprobe -v error -select_streams a:0 \
+  -show_entries format=duration -of default=nk=1:nw=1 "${song}" 2>/dev/null || true)"
+[ -n "${duration}" ] || die 4 "no audio stream in: ${song}"
+
+# --- 2. per-window RMS energy via astats --------------------------------
+# Slice the track into <window>-second chunks; read mean RMS level (dB),
+# normalise to 0..1 where -60dB→0 and 0dB→1. These energies feed BOTH the
+# rms-merge method and the per-section labelling of every method.
+n_windows="$(awk -v d="${duration}" -v w="${window}" 'BEGIN{
+  n = int(d / w); if (n * w < d) n++; if (n < 1) n = 1; print n }')"
+
+win_starts=""; win_energy=""
+i=0
+while [ "${i}" -lt "${n_windows}" ]; do
+  start="$(awk -v i="${i}" -v w="${window}" 'BEGIN{printf "%.3f", i*w}')"
+  rms_db="$(ffmpeg -hide_banner -nostats -ss "${start}" -t "${window}" -i "${song}" \
+    -af astats=metadata=1:reset=1 -f null - 2>&1 \
+    | awk -F': ' '/RMS level dB/ {v=$2} END{print v}')"
+  case "${rms_db}" in ""|*inf*|*nan*) rms_db=-60 ;; esac
+  norm="$(awk -v x="${rms_db}" 'BEGIN{
+    v=(x+60)/60; if(v<0)v=0; if(v>1)v=1; printf "%.3f", v }')"
+  win_starts="${win_starts}${start}\n"
+  win_energy="${win_energy}${norm}\n"
+  i=$((i + 1))
+done
+
+# --- 3. silencedetect boundaries ----------------------------------------
+# Real quiet gaps split the track at musically-meaningful points far more
+# reliably than RMS deltas on a compressed master. Collect the midpoints
+# of detected silences as candidate section boundaries.
+sil_bounds="$(ffmpeg -hide_banner -nostats -i "${song}" \
+  -af "silencedetect=noise=${silence_db}dB:d=${silence_min}" -f null - 2>&1 \
+  | awk '
+      /silence_start/ { for(i=1;i<=NF;i++) if($i=="silence_start:") s=$(i+1) }
+      /silence_end/   { for(i=1;i<=NF;i++) if($i=="silence_end:")   { e=$(i+1); printf "%.3f\n", (s+e)/2 } }
+    ' 2>/dev/null || true)"
+n_sil="$(printf '%s' "${sil_bounds}" | sed '/^$/d' | wc -l | tr -d ' ')"
+
+# --- 4. choose method + build section boundaries ------------------------
+# A method needs >= 3 sections (>= 2 internal boundaries) to count as
+# "structure found"; otherwise degrade to the next method.
+method=""
+boundaries=""   # internal cut points (excluding 0 and duration)
+
+if [ "${n_sil}" -ge 2 ]; then
+  method="silence"
+  boundaries="$(printf '%s\n' "${sil_bounds}" | sed '/^$/d' \
+    | awk -v d="${duration}" '$1>0.5 && $1<d-0.5' | sort -n | uniq)"
+fi
+
+if [ -z "${method}" ]; then
+  # greedy-merge adjacent RMS windows; keep a boundary on energy delta > 0.12
+  rms_bounds="$(paste <(printf '%b' "${win_starts}") <(printf '%b' "${win_energy}") \
+    | awk -v d="${duration}" '
+        { st[NR]=$1; en[NR]=$2; cnt=NR }
+        END {
+          prev=en[1]
+          for(k=2;k<=cnt;k++){
+            if ((en[k]-prev>0.12)||(prev-en[k]>0.12)) { if(st[k]>0.5 && st[k]<d-0.5) print st[k] }
+            prev=en[k]
+          }
+        }')"
+  n_rms="$(printf '%s' "${rms_bounds}" | sed '/^$/d' | wc -l | tr -d ' ')"
+  if [ "${n_rms}" -ge 2 ]; then
+    method="rms"
+    boundaries="$(printf '%s\n' "${rms_bounds}" | sed '/^$/d' | sort -n | uniq)"
+  fi
+fi
+
+warning=""
+if [ -z "${method}" ]; then
+  method="interval"
+  warning="track is structurally flat (no usable silence or energy structure); sections are fixed ${interval}s intervals, not musical cuts"
+  boundaries="$(awk -v d="${duration}" -v iv="${interval}" 'BEGIN{
+    for(t=iv; t<d-0.5; t+=iv) printf "%.3f\n", t }')"
+fi
+
+# --- 5. assemble sections, label, emit JSON -----------------------------
+# Boundaries → [0, b1, b2, ..., duration] section edges. Energy per section
+# = mean of the RMS windows whose start falls inside it.
+printf '%s' "${boundaries}" \
+  | sed '/^$/d' \
+  | awk -v d="${duration}" -v method="${method}" -v warning="${warning}" \
+        -v wins="$(printf '%b' "${win_starts}")" -v ens="$(printf '%b' "${win_energy}")" '
+    BEGIN {
+      nw=split(wins, ws, "\n"); split(ens, es, "\n")
+      # build edges
+      ne=0; edges[ne++]=0
+    }
+    { edges[ne++]=$1+0 }
+    END {
+      edges[ne++]=d+0
+      # mean energy across all windows for relative labelling
+      sum=0; c=0
+      for(k=1;k<=nw;k++){ if(ws[k]!=""){ sum+=es[k]; c++ } }
+      mean=(c?sum/c:0)
+      printf "{\"duration\": %.3f, \"method\": \"%s\"", d, method
+      if (warning != "") { gsub(/"/,"\\\"",warning); printf ", \"warning\": \"%s\"", warning }
+      printf ", \"sections\": ["
+      segs=ne-1
+      for(j=0;j<segs;j++){
+        s=edges[j]; e=edges[j+1]
+        # mean energy of windows starting within [s,e)
+        es_sum=0; es_c=0
+        for(k=1;k<=nw;k++){ if(ws[k]!=""){ if(ws[k]+0>=s && ws[k]+0<e){ es_sum+=es[k]; es_c++ } } }
+        energy=(es_c?es_sum/es_c:mean)
+        if (j==0) label="intro"
+        else if (j==segs-1) label=(energy<mean?"outro":"drop")
+        else if (energy>=mean+0.10) label="drop"
+        else if (energy<=mean-0.10) label="breakdown"
+        else label="build"
+        sep=(j<segs-1)?",":""
+        printf "{\"start\": %.3f, \"end\": %.3f, \"energy\": %.3f, \"label\": \"%s\"}%s", s, e, energy, label, sep
+      }
+      print "]}"
+    }'