Data-Path Convention

How command, agent, skill, and hook-prompt prose should refer to user data vs plugin-shipped assets after the M0 migration. One token, resolved inline, so the prose Claude reads is directly actionable — no indirection, no stale in-plugin paths.

The two roots

Root	Token in prose	Holds	Moves on migration?
Data root	`${LINKEDIN_STUDIO_DATA:-$HOME/.claude/linkedin-studio}`	the user's real data (voice profile, analytics, drafts, plans, …)	yes — auto-migrated out of the plugin on session-start
Plugin root	`${CLAUDE_PLUGIN_ROOT}`	read-only ships (templates, checklists, references, fonts, framework scaffolds)	no — these stay in the plugin

The data root mirrors the state file (~/.claude/linkedin-studio.local.md). The default is overridable by the single env var LINKEDIN_STUDIO_DATA; the deprecated aliases ANALYTICS_ROOT / STATE_FILE / PLUGIN_ROOT are honored for one minor version. This generalizes the proven newsletter pattern ${LTL_SERIES_ROOT:-$HOME/linkedin-series} (commands/newsletter.md) to all data.

Data-root layout (mirrors brief §7.1)

${LINKEDIN_STUDIO_DATA:-$HOME/.claude/linkedin-studio}/
  voice-samples/        authentic-voice-samples.md   chronicle-voice-drift-log.md
  analytics/            exports/ posts/ weekly-reports/ monthly-reports/ ab-tests/ content-history.md
  drafts/               queue.json  week-*/  carousel/  multiplatform/  repurposed/
  profile/              user-profile.md
  frameworks/           <slug>.md
  audience-insights/    demographics.md  engagement-patterns.md
  examples/             high-engagement-posts.md
  templates/            my-post-templates.md
  plans/                <weekly|monthly>-plan-*.md

The prose rule

A path to user data → the data-root token. Write the full inline form ${LINKEDIN_STUDIO_DATA:-$HOME/.claude/linkedin-studio}/<subpath> — never a bare assets/<x>/ and never ${CLAUDE_PLUGIN_ROOT}/assets/<x>/ for data. The inline :-default expansion means the prose is self-resolving; do not write "the data dir's <x>" and force a lookup into this doc.
A path to a plugin-shipped read-only asset → keep ${CLAUDE_PLUGIN_ROOT}. Templates (config/*.template.*), checklists, references/, fonts, and framework scaffolds ship with the plugin and stay there.
Preserve existing graceful-degradation guards. "if it exists", placeholder / sentinel checks, and <5-sample silent-skips stay as written — only the path token changes.

Scaffold fallback (the COPY classes + the voice placeholder)

Four data files ship a seed/scaffold in-plugin and a canonical instance external: examples/high-engagement-posts.md, audience-insights/{demographics,engagement-patterns}.md, templates/my-post-templates.md. The voice profile is similar — the plugin ships a placeholder at assets/voice-samples/authentic-voice-samples.md; the user's real profile lives external. Readers prefer the external instance and fall back to the in-plugin seed when external is absent (the code does this in personalization-score.mjs; prose keeps its "if it exists" guard). The external instance is canonical — migration never clobbers it.

Why inline, not indirection (the Step-14 GATE finding)

The prototype on the voice-readers family (19 files, 38 refs) measured the open question from brief D3: can a convention reduce edits, or do commands need literal paths for Claude to act on? Outcome: command prose that tells Claude to read a file needs a resolvable path on the line. A "the data dir's voice-samples/ (see this doc)" reference adds a lookup hop and is not directly actionable. The inline ${LINKEDIN_STUDIO_DATA:-…}/… token is both self-resolving and points here. So the convention does not cut the edit count below ~1 per reference — it makes every edit a uniform, mechanical token swap instead of a bespoke per-line decision, with this doc as the single source of truth. Step 15 applies the same uniform token to the remaining families (D3 realized as one token — not a re-decision).

4.1 KiB Raw Blame History