portable-agent-layer 0.54.3 → 0.55.0

package/assets/skills/analyze-pdf/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: analyze-pdf
-description: Download and analyze PDF files from URLs or local paths — extract text, answer questions, summarize content. Use when analyzing, reading, or extracting information from a PDF.
+description: "Download and analyze PDF files from URLs or local paths — extract text, answer questions, summarize content. Use when analyzing, reading, or extracting information from a PDF."
 argument-hint: <URL or file path>
 ---
 

package/assets/skills/analyze-youtube/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: analyze-youtube
-description: Analyze YouTube videos using Gemini's native video understanding — summarize, extract insights, answer questions. Use when analyzing, summarizing, or extracting information from a YouTube video.
+description: "Analyze YouTube videos using Gemini's native video understanding — summarize, extract insights, answer questions. Use when analyzing, summarizing, or extracting information from a YouTube video."
 argument-hint: <YouTube URL>
 ---
 

package/assets/skills/consulting-report/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: consulting-report
-description: Build a beautifully-typeset consulting-report PDF from a typed data file and a React layout. Use when generating an assessment, strategic review, operational readiness check, or any McKinsey-style consulting deliverable as a PDF.
+description: "Build a beautifully-typeset consulting-report PDF from a typed data file and a React layout. Use when generating an assessment, strategic review, operational readiness check, or any McKinsey-style consulting deliverable as a PDF."
 argument-hint: scaffold <target-dir> | dev <report-dir> | <report-dir> (render PDF)
 ---
 

package/assets/skills/council/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: council
-description: Multi-perspective parallel debate on a decision — 3-5 independent perspectives argue in parallel, then synthesize into a verdict. Use when debating, weighing options, or needing multiple viewpoints on a question.
+description: "Multi-perspective parallel debate on a decision — 3-5 independent perspectives argue in parallel, then synthesize into a verdict. Use when debating, weighing options, or needing multiple viewpoints on a question."
 argument-hint: <question or decision>
 ---
 

package/assets/skills/create-pdf/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-pdf
-description: Convert markdown files into a styled PDF. Use when creating a PDF from existing markdown files, combining markdown into a report, or converting .md to .pdf.
+description: "Convert markdown files into a styled PDF. Use when creating a PDF from existing markdown files, combining markdown into a report, or converting .md to .pdf."
 argument-hint: <file paths, glob pattern, or directory containing .md files>
 ---
 

package/assets/skills/create-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-skill
-description: Create a new personal skill for this user, scaffolded into their own ~/.pal/skills/ and linked into every installed agent. Use when the user asks to create a skill, add a capability, build a custom command, or "make a skill that…".
+description: "Create a new personal skill for this user, scaffolded into their own ~/.pal/skills/ and linked into every installed agent. Use when the user asks to create a skill, add a capability, build a custom command, or \"make a skill that…\"."
 argument-hint: <skill name> <skill description>
 ---
 

package/assets/skills/entities/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: entities
-description: Maintain the personal knowledge graph of people and companies. Detect named entities in any content (article, video, paste, conversation), upsert them to ~/.pal/memory/knowledge/, and surface what's already known. Use proactively whenever named entities appear — don't wait to be asked.
+description: "Maintain the personal knowledge graph of people and companies. Detect named entities in any content (article, video, paste, conversation), upsert them to ~/.pal/memory/knowledge/, and surface what's already known. Use proactively whenever named entities appear — don't wait to be asked."
 argument-hint: <content, URL, or pasted text>
 ---
 

package/assets/skills/extract-wisdom/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: extract-wisdom
-description: Extract structured insights from content (articles, videos, podcasts). Use when extracting wisdom, key takeaways, or structured insights from any content.
+description: "Extract structured insights from content (articles, videos, podcasts). Use when extracting wisdom, key takeaways, or structured insights from any content."
 argument-hint: <content or URL>
 ---
 

package/assets/skills/first-principles/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: first-principles
-description: Break down a problem to its fundamental constraints and build up a solution. Use when decomposing complexity, challenging assumptions, or finding root causes.
+description: "Break down a problem to its fundamental constraints and build up a solution. Use when decomposing complexity, challenging assumptions, or finding root causes."
 argument-hint: <problem>
 ---
 

package/assets/skills/frontend-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontend-design
-description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
+description: "Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics."
 license: Complete terms in LICENSE.txt
 ---
 

package/assets/skills/fyzz-chat-api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fyzz-chat-api
-description: Query Fyzz Chat conversations and projects via the REST API. Use when looking up conversations, searching chat history, or listing projects in Fyzz Chat.
+description: "Query Fyzz Chat conversations and projects via the REST API. Use when looking up conversations, searching chat history, or listing projects in Fyzz Chat."
 argument-hint: <conversations|projects> [options]
 ---
 

package/assets/skills/pal-analyze/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pal-analyze
-description: Run learning analysis — surface rating trends, recurring failure patterns, and graduation candidates. Use when learning analysis is due, or when the user asks about performance patterns, low ratings, or what to improve.
+description: "Run learning analysis — surface rating trends, recurring failure patterns, and graduation candidates. Use when learning analysis is due, or when the user asks about performance patterns, low ratings, or what to improve."
 argument-hint: [optional: --actionable for AI-generated recommendations]
 ---
 

package/assets/skills/pal-reflect/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pal-reflect
-description: Run relationship reflect — promote recurring behavioral observations into tracked opinions. Use when relationship reflect is due, or when the user asks to review what patterns have been observed.
+description: "Run relationship reflect — promote recurring behavioral observations into tracked opinions. Use when relationship reflect is due, or when the user asks to review what patterns have been observed."
 argument-hint: [optional: --dry-run to preview without writing]
 ---
 

package/assets/skills/playwright/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: playwright
-description: Capture a screenshot of a URL or local page and load it into context for a visual check. Use when asked to check visually, use playwright, screenshot a page, see or look at the design yourself, or verify a layout on desktop and mobile widths.
+description: "Capture a screenshot of a URL or local page and load it into context for a visual check. Use when asked to check visually, use playwright, screenshot a page, see or look at the design yourself, or verify a layout on desktop and mobile widths."
 argument-hint: <url> [--viewport WxH] [--full-page] [--selector <css>]
 ---
 

package/assets/skills/presentation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: presentation
-description: "Build branded HTML presentations from markdown using Reveal.js. Multi-template registry per user (each template = brand color, logo, fonts, footer, aspect). Per-deck workflow: scaffold → edit one markdown file per slide in slides/ → build → present. Output: a `<deck-name>/` subdir with a self-contained HTML and a concatenated markdown sibling. 14 layouts including data-display patterns (big-stat, metric-grid). Use when creating slide decks, talks, workshop slides, lectures, or pitch decks."
+description: "Build branded HTML presentations from markdown using Reveal.js. Multi-template registry per user (each template = brand color, logo, fonts, footer, aspect). Per-deck workflow: scaffold → edit one markdown file per slide in slides/ → build → present. Output: a per-deck subdir with a self-contained HTML and a concatenated markdown sibling. 14 layouts including data-display patterns (big-stat, metric-grid). Use when creating slide decks, talks, workshop slides, lectures, or pitch decks."
 argument-hint: <deck-dir> to build, OR `setup-template` to add a brand template, OR `new <deck-dir> --template <name>` to scaffold a deck, OR `list-templates`
 ---
 

package/assets/skills/projects/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: projects
-description: Project context management. PROACTIVE — use when the user references a project (by name or as "this repo", "current work"), asks to add/update/complete a project, says "store under <project>", "track this", "what am I working on", "my projects", "my priorities".
+description: "Project context management. PROACTIVE — use when the user references a project (by name or as \"this repo\", \"current work\"), asks to add/update/complete a project, says \"store under a named project\", \"track this\", \"what am I working on\", \"my projects\", \"my priorities\". Also triggered by ISC/ISA terminology — ISC stands for Ideal State Criteria, a project's verifiable done-conditions stored as `ISC-N:` lines in the Criteria section of its ISA.md spec. Phrases like \"ISC\", \"open/opening the ISC\", \"open ISCs\" (unfinished criteria), \"create/creating a ticket for a project\", \"new ticket\", or \"project ticket\" all map here: use `list-isc` to read them, `add-isc` to create one, `complete-isc`/`reopen-isc` to change status."
 argument-hint: [list | create | resume | add-next | add-blocker | add-decision | add-handoff | update-section | criteria | isa-init | complete | archive | pause]
 ---
 

package/assets/skills/reflect/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: reflect
-description: Diagnose why a PAL behavior did not trigger as expected — trace hooks, instructions, and logic to find the gap. Use when a hook, skill, or automation didn't fire or behaved unexpectedly.
+description: "Diagnose why a PAL behavior did not trigger as expected — trace hooks, instructions, and logic to find the gap. Use when a hook, skill, or automation didn't fire or behaved unexpectedly."
 argument-hint: <what went wrong>
 ---
 

package/assets/skills/research/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: research
-description: Multi-agent parallel research — quick/standard/extensive modes with specialized researcher agents for depth, breadth, and verification. Use when researching a topic, finding information, or investigating something thoroughly.
+description: "Multi-agent parallel research — quick/standard/extensive modes with specialized researcher agents for depth, breadth, and verification. Use when researching a topic, finding information, or investigating something thoroughly."
 argument-hint: <topic or question>
 ---
 

package/assets/skills/review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review
-description: Security-focused code review with severity ratings. Use when reviewing code for security issues, vulnerabilities, or OWASP concerns.
+description: "Security-focused code review with severity ratings. Use when reviewing code for security issues, vulnerabilities, or OWASP concerns."
 argument-hint: [file or directory]
 ---
 

package/assets/skills/summarize/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: summarize
-description: Structured summarization of documents, URLs, or conversations. Use when summarizing content, creating overviews, or distilling key points.
+description: "Structured summarization of documents, URLs, or conversations. Use when summarizing content, creating overviews, or distilling key points."
 argument-hint: <document, URL, or topic>
 ---
 

package/assets/skills/telos/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: telos
-description: Personal context management. Use when discussing goals, beliefs, challenges, identity, updating telos, life context, changing a goal, what do I believe, current obstacles, mission, or strategies.
+description: "Personal context management. Use when discussing goals, beliefs, challenges, identity, updating telos, life context, changing a goal, what do I believe, current obstacles, mission, or strategies."
 argument-hint: [area to view or update]
 ---
 

package/assets/skills/think/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: think
-description: Thinking mode router — selects the right analytical approach for a question. Use when thinking through a problem, analyzing deeply, brainstorming ideas, debating options, decomposing to root cause, challenging assumptions, or exploring from multiple perspectives.
+description: "Thinking mode router — selects the right analytical approach for a question. Use when thinking through a problem, analyzing deeply, brainstorming ideas, debating options, decomposing to root cause, challenging assumptions, or exploring from multiple perspectives."
 argument-hint: <question or topic>
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.54.3",
+  "version": "0.55.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/index.ts

@@ -1087,10 +1087,12 @@ async function install(targets: Targets) {
   const { scaffoldTelos, scaffoldPalSettings } = await import("../targets/lib");
   const { promptIdentity } = await import("./setup-identity");
   const { promptTelos } = await import("./setup-telos");
+  const { promptAttribution } = await import("./setup-attribution");
   scaffoldTelos();
   scaffoldPalSettings();
   await promptIdentity();
   await promptTelos();
+  await promptAttribution();
 
   if (targets.claude) {
     console.log("━━━ Claude Code ━━━");

package/src/cli/setup-attribution.ts

@@ -0,0 +1,49 @@
+/**
+ * Optional git co-author attribution — one-time opt-in prompt.
+ *
+ * Asked once during `pal install` (covers fresh init and the reinstall that
+ * `pal cli update` runs). The `decided` flag makes it ask exactly once: new
+ * users see it at init, existing users see it on their next update, nobody is
+ * nagged again. The choice is applied to ~/.claude/settings.json at install time.
+ */
+
+import * as clack from "@clack/prompts";
+import {
+  identity,
+  raw as readSettings,
+  write as writeSettings,
+} from "../hooks/lib/settings";
+import { buildAttributionText } from "../targets/lib";
+
+/** Prompt once for git attribution opt-in. No-op if already decided or non-TTY. */
+export async function promptAttribution(): Promise<void> {
+  if (!process.stdin.isTTY) return;
+
+  const settings = { ...readSettings() };
+  if (settings.attribution?.decided) return;
+
+  const name = identity().ai.name;
+  const { commit, pr } = buildAttributionText(name);
+
+  clack.intro("Git attribution");
+  clack.note(
+    `commit: ${commit}\npr:     ${pr}`,
+    `Credit ${name} on the commits & PRs it makes?`
+  );
+
+  const enabled = await clack.confirm({
+    message: `Add this ${name} co-author credit?`,
+    initialValue: true,
+  });
+  if (clack.isCancel(enabled)) {
+    clack.cancel("Skipped — will ask again next time");
+    return;
+  }
+
+  settings.attribution = { enabled: enabled === true, decided: true };
+  writeSettings(settings);
+  const state = enabled ? `${name} attribution on` : "Attribution off";
+  clack.outro(
+    `${state} ✓  ·  change later: edit pal-settings.json, then run 'pal install'`
+  );
+}

package/src/hooks/lib/settings.ts

@@ -23,6 +23,8 @@ export interface PalSettingsData {
   };
   loadAtStartup?: { files?: string[] };
   dynamicContext?: Record<string, boolean>;
+  /** Git co-author attribution opt-in. `decided` gates the one-time prompt. */
+  attribution?: { enabled?: boolean; decided?: boolean };
   [key: string]: unknown;
 }
 

package/src/targets/claude/install.ts

@@ -8,8 +8,10 @@ import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { regenerateIfNeeded } from "../../hooks/lib/claude-md";
 import { assets, palHome, palPkg, platform } from "../../hooks/lib/paths";
+import { identity, raw as readPalSettings } from "../../hooks/lib/settings";
 import {
   addStatuslineConfig,
+  applyAttribution,
   copyAgents,
   copyPalDocs,
   copySkills,
@@ -50,6 +52,16 @@ let merged = mergeSettings(existing, template);
 // Add platform-specific statusLine config
 merged = addStatuslineConfig(merged);
 
+// Apply the user's git-attribution choice (composed from identity name at runtime —
+// never committed to assets). Only acts once the opt-in prompt has been answered.
+const attribution = readPalSettings().attribution;
+if (attribution?.decided) {
+  merged = applyAttribution(merged, {
+    enabled: attribution.enabled === true,
+    name: identity().ai.name,
+  });
+}
+
 writeJson(SETTINGS, merged);
 log.success("Merged PAL settings into settings.json");
 

package/src/targets/lib.ts

@@ -43,6 +43,42 @@ export function writeJson(path: string, data: unknown): void {
   writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, "utf-8");
 }
 
+// --- Git attribution ---
+
+/** Public PAL repository — the link surfaced in commit/PR co-author credits. */
+export const PAL_REPO_URL = "https://github.com/kovrichard/portable-agent-layer";
+
+/** Build the commit footer (bare URL, autolinks on GitHub) and PR body line (markdown link). */
+export function buildAttributionText(
+  name: string,
+  repoUrl: string = PAL_REPO_URL
+): { commit: string; pr: string } {
+  return {
+    commit: `Co-authored by ${name} · ${repoUrl}`,
+    pr: `Co-authored by [${name}](${repoUrl})`,
+  };
+}
+
+/**
+ * Apply the user's git-attribution choice to a Claude settings object.
+ * Enabled → fill attribution.commit/pr and drop Claude's own byline (includeCoAuthoredBy:false).
+ * Disabled → clear PAL attribution and restore Claude's default byline.
+ */
+export function applyAttribution(
+  settings: Settings,
+  opts: { enabled: boolean; name: string; repoUrl?: string }
+): Settings {
+  const result = { ...settings };
+  if (opts.enabled) {
+    result.attribution = buildAttributionText(opts.name, opts.repoUrl);
+    result.includeCoAuthoredBy = false;
+  } else {
+    result.attribution = { commit: "", pr: "" };
+    if (result.includeCoAuthoredBy === false) delete result.includeCoAuthoredBy;
+  }
+  return result;
+}
+
 /** Resolve the VS Code user settings.json path cross-platform. Returns null on unknown platforms. */
 export function vscodeSettingsFile(): string | null {
   const h = homedir();

package/src/tools/skill-doctor.ts

@@ -32,6 +32,7 @@ export interface DoctorReport {
 interface ParsedSkill {
   name: string | null;
   description: string | null;
+  descriptionQuoted: boolean;
   body: string;
 }
 
@@ -44,13 +45,19 @@ const MAX_BODY_LINES = 500;
 function parseSkill(content: string): ParsedSkill {
   const parts = content.split(/^---\s*$/m);
   if (parts.length < 3) {
-    return { name: null, description: null, body: content };
+    return { name: null, description: null, descriptionQuoted: false, body: content };
   }
   const frontmatter = parts[1];
   const body = parts.slice(2).join("---");
   const name = /^name:\s*"?(.+?)"?\s*$/m.exec(frontmatter)?.[1] ?? null;
-  const description = /^description:\s*"?(.+?)"?\s*$/m.exec(frontmatter)?.[1] ?? null;
-  return { name, description, body };
+  const rawDescription = /^description:[ \t]*(.*?)\s*$/m.exec(frontmatter)?.[1] ?? null;
+  const descriptionQuoted =
+    rawDescription !== null &&
+    rawDescription.length >= 2 &&
+    rawDescription.startsWith('"') &&
+    rawDescription.endsWith('"');
+  const description = descriptionQuoted ? rawDescription.slice(1, -1) : rawDescription;
+  return { name, description, descriptionQuoted, body };
 }
 
 /** Remove fenced and inline code so prose checks don't trip on examples. */
@@ -89,7 +96,7 @@ export function lintSkill(skillDir: string): DoctorReport {
         `skill file is "${skillFile}" — must be exactly "SKILL.md" or the skill is silently ignored`
       );
 
-  const { name, description, body } = parseSkill(
+  const { name, description, descriptionQuoted, body } = parseSkill(
     readFileSync(resolve(skillDir, skillFile), "utf-8")
   );
 
@@ -141,6 +148,13 @@ export function lintSkill(skillDir: string): DoctorReport {
           "description.length",
           `${description.length} chars exceeds ${MAX_DESCRIPTION}`
         );
+    descriptionQuoted
+      ? add("pass", "description.quoted", "value is wrapped in double quotes")
+      : add(
+          "warn",
+          "description.quoted",
+          'value is not wrapped in double quotes — unquoted YAML mis-parses on colons, commas, and quotes; wrap it in "..." (escaping any inner " as \\")'
+        );
     /<[^>]+>/.test(description)
       ? add(
           "warn",
@@ -189,15 +203,21 @@ export function lintSkill(skillDir: string): DoctorReport {
 
   // ── reference depth (one level deep) ──
   const linkRe = /\[[^\]]+\]\(([^)]+\.md)\)/g;
-  const hasMdLink = /\[[^\]]+\]\([^)]+\.md\)/;
+  const skillFilePath = resolve(skillDir, skillFile);
+  // A reference back to the entry SKILL.md is a return-link, not a deeper chain.
+  const isDeeperRef = (target: string) =>
+    !/^https?:/.test(target) && resolve(skillDir, target) !== skillFilePath;
   let nested = false;
   for (const m of body.matchAll(linkRe)) {
     const target = m[1];
-    if (/^https?:/.test(target)) continue;
+    if (!isDeeperRef(target)) continue;
     const targetPath = resolve(skillDir, target);
     if (!existsSync(targetPath)) continue;
     const refContent = readFileSync(targetPath, "utf-8");
-    if (hasMdLink.test(refContent)) {
+    const onward = [...refContent.matchAll(linkRe)]
+      .map((mm) => mm[1])
+      .filter(isDeeperRef);
+    if (onward.length > 0) {
       nested = true;
       add(
         "warn",
@@ -209,7 +229,12 @@ export function lintSkill(skillDir: string): DoctorReport {
   if (!nested) add("pass", "references.depth", "references are one level deep");
 
   // ── windows-style paths ──
-  /\b[\w.-]+\\[\w.-]+\.(py|ts|js|sh|md|json)\b/.test(body)
+  // Skip lines that are deliberate Windows examples (cmd.exe / %ENV% paths) —
+  // a cross-platform skill may legitimately document the Windows invocation.
+  const winPathRe = /\b[\w.-]+\\[\w.-]+\.(py|ts|js|sh|md|json)\b/;
+  const isIntentionalWindows = (line: string) =>
+    /%[A-Z_]+%/.test(line) || /cmd\.exe/i.test(line);
+  body.split("\n").some((l) => winPathRe.test(l) && !isIntentionalWindows(l))
     ? add("warn", "paths", "Windows-style backslash path found — use forward slashes")
     : add("pass", "paths", "forward-slash paths");