@agentled/cli 0.6.7 → 0.7.2

package/dist/utils/agentled-home-content.js

@@ -0,0 +1,414 @@
+/**
+ * Bundled docs written into `~/.agentled/docs/` on `agentled setup` runs.
+ *
+ * Embedded as string constants so they ship with the CLI release (same
+ * pattern as GOTCHAS.md in workspace-folder.ts).
+ *
+ * **`docs/` is CLI-managed.** Treat the bundled files as read-only — they
+ * are unconditionally rewritten when `HOME_CONTENT_VERSION` advances
+ * past the on-disk marker. Anyone who wants to edit local notes should
+ * put them in `~/.agentled/docs/local/` (never touched by the bootstrap)
+ * or in the per-workspace `agentled_<slug>/` folder.
+ *
+ * `HOME_CONTENT_VERSION` is intentionally **decoupled from the CLI
+ * package version** — it is an opaque integer that bumps only when one
+ * of the constants below changes. A CLI patch bump that touches no doc
+ * content does not refresh `~/.agentled/`.
+ */
+/**
+ * Bump this every time any HOME_README_MD / WORKFLOW_SHAPE_MD /
+ * GETTING_STARTED_MD / GOTCHAS_MD / PATTERNS_MD constant changes.
+ *
+ * Do NOT pin to the CLI semver — that bumps for unrelated reasons and
+ * causes spurious doc rewrites on every patch release.
+ */
+export const HOME_CONTENT_VERSION = '3';
+export const HOME_README_MD = `# AgentLed
+
+You've installed the AgentLed CLI. Your AI agent (Claude Code, Codex, Cursor, Claude Desktop, Windsurf) can now build and run workflows for you.
+
+## Talk to your agent
+
+Once \`agentled setup\` is done and you've restarted your MCP client, just describe what you want. The agent has access to AgentLed's MCP tools, your workspace's knowledge graph, and 100+ integrations.
+
+Try one:
+- "Source fintech CTOs in Europe via search and LinkedIn, score by ICP fit, email me the top 10 daily."
+- "Qualify inbound form submissions and route the high-score ones to a Slack channel."
+- "Pull competitor pricing pages weekly, summarize changes, send a diff report."
+
+## What lives here
+
+- \`config.json\` — saved workspace profiles (managed by \`agentled auth\`).
+- \`docs/\` — brief design guide your agent reads on session start. **CLI-managed: treat as read-only.** Files here are rewritten when the bundled doc version advances.
+- \`docs/local/\` — your own notes. **Never overwritten by the CLI.** Put any edits or additions here.
+- \`examples/scaffolds/\` — preflight-clean pipeline templates your agent adapts to your intent. Also CLI-managed.
+
+Per-workspace artifacts (logs, dryruns, decisions, drafts) live in \`agentled_<workspace-slug>/\` in your project directory — one folder per workspace.
+
+## CLI commands
+
+\`\`\`
+agentled --help              # list commands
+agentled auth current        # active workspace
+agentled workflows list      # workflows in your workspace
+agentled examples            # browse pattern templates
+\`\`\`
+
+## Open patterns reference
+
+For extended workflow patterns and anti-patterns beyond the bundled scaffolds, see the public agentic-ops repo: https://github.com/Agentled/agentic-ops. Optional reading — the bundled \`docs/\` and \`examples/scaffolds/\` are sufficient for first-workflow building.
+`;
+export const WORKFLOW_SHAPE_MD = `# Workflow shape — source → list → orchestrator → outreach
+
+The canonical AgentLed workflow shape, optimized for re-runnable, dedup-safe pipelines.
+
+## The list is the spine
+
+A KG list (e.g. \`kg.list.leads\`) holds every entity your business cares about. Multiple sourcing workflows write into the same list. One orchestrator workflow reads from it, processes, and transitions row state.
+
+Two indexes make this efficient:
+
+1. **\`userKey\`** — caller-supplied dedup index. Use a stable identifier per row (domain, LinkedIn URL, email hash). \`kg.upsert-rows\` with the same \`userKey\` writes to the same row, every time, forever. No table scan, no duplicate explosion.
+2. **\`status\`** — the queue marker. New rows start at \`status: "new"\`. The orchestrator filters by status, processes only rows in the relevant state, and transitions status as it goes (\`scored\`, \`qualified\`, \`contacted\`, \`rejected\`).
+
+## Sourcing workflows (1+)
+
+Each sourcing workflow has one job: find entities, write them with a \`userKey\` and \`status: "new"\`. Use \`mergeStrategy: "merge"\` so downstream-added fields (scores, notes) survive a re-source. Many sourcing workflows can write to the same list.
+
+\`\`\`json
+{
+  "id": "save-to-list",
+  "type": "appAction",
+  "app": { "id": "kg", "actionId": "kg.upsert-rows", "source": "native" },
+  "stepInputData": {
+    "listKey": "leads",
+    "rows": "{{steps.extract.items}}",
+    "mergeStrategy": "merge",
+    "status": "new"
+  }
+}
+\`\`\`
+
+> Note: pass \`rows\` directly as the template variable — do NOT wrap it in \`JSON.stringify\` or quote-escape the array. The serializer inlines the raw value (see GOTCHAS.md #12). The \`filters\` field on \`kg.read-list\` (below) is the exception — it expects a JSON-string body, not an array, so the escaped object literal is correct there.
+
+## Orchestrator workflow (1)
+
+Schedule trigger → \`kg.read-list\` filtered by \`status: "new"\` → loop → score / qualify / route → \`kg.update-rows\` to transition status.
+
+\`\`\`json
+// Step 1: read pending rows
+{
+  "id": "read-pending",
+  "type": "appAction",
+  "app": { "id": "kg", "actionId": "kg.read-list", "source": "native" },
+  "stepInputData": { "listKey": "leads", "filters": "{\\"status\\": \\"new\\"}", "limit": "50" }
+}
+
+// Step N: transition status
+{
+  "id": "mark-scored",
+  "type": "appAction",
+  "app": { "id": "kg", "actionId": "kg.update-rows", "source": "native" },
+  "stepInputData": {
+    "listKey": "leads",
+    "rowIds": "{{steps.score.processedIds}}",
+    "fieldUpdates": "{\\"status\\": \\"scored\\"}"
+  }
+}
+\`\`\`
+
+## Outreach workflow (1, optional)
+
+Often folded into the orchestrator. When separate: schedule trigger → \`kg.read-list\` filtered by \`status: "qualified"\` → compose email (with approval gate) → \`schedule-email\` → mark \`status: "contacted"\`.
+
+Why separate: outreach has different cadence (e.g. daily, batch-limited) than scoring (continuous), and you may want different approval gates per channel.
+
+## Status conventions
+
+| Value | Meaning |
+|-------|---------|
+| \`new\` | Sourced, not yet processed |
+| \`scored\` | Enriched + scored, awaiting routing |
+| \`qualified\` | Passes ICP / threshold, ready for outreach |
+| \`rejected\` | Failed scoring criteria |
+| \`contacted\` | Outreach sent |
+| \`replied\` | Reply received (set by an inbound workflow) |
+
+Use whatever values fit your domain. The pattern is: sourcing always sets one status, the orchestrator transitions through ≥1 status, reads always filter by status.
+
+## Why the spine matters
+
+- Multiple sourcing channels converge — one canonical list, no fan-out logic in each producer.
+- Re-running a source is idempotent — \`userKey\` dedup.
+- Re-running the orchestrator is idempotent — status filter excludes done rows.
+- Each phase has its own cadence — sourcing daily, orchestrator hourly, outreach business hours.
+- Failures are scoped — a bad source doesn't pollute scoring; a bad scorer doesn't break sourcing.
+
+## Pausing for human input — decouple via the list
+
+When a workflow needs human input partway through (e.g., "meeting done, capture the outcome and transcript URL, then continue scoring"), **don't try to pause inside one workflow**. Split it across the KG list spine — same shape as everything else.
+
+\`\`\`
+Workflow A (the producer)
+  … reaches the point that needs human input …
+  → kg.update-rows: status = "needs-meeting-outcome"
+  → milestone (A is done; row sits in the list)
+
+Workflow B (user-triggered, manual)
+  → trigger: manual, with input page asking for:
+        - meeting_outcome (text)
+        - transcript_url   (url)
+  → kg.update-rows: status = "input-received", fieldUpdates = { outcome, transcript }
+  → milestone
+
+Workflow C (the consumer, scheduled)
+  → kg.read-list filtered by status = "input-received"
+  → … continue scoring / qualifying using outcome + transcript …
+  → kg.update-rows: status = "scored"
+\`\`\`
+
+Why decouple:
+- Each workflow has its own cadence and trigger — the producer runs on schedule, the user-triggered B runs whenever the user has the data, the consumer runs on schedule. None blocks the other.
+- The KG row carries the state. If the user fills in the form a week later, it just works — nothing was hanging in memory waiting.
+- A new agent (or a teammate) can act on rows in any state at any time — the substrate is shared.
+- You can have multiple producers, multiple human-input forms (different roles, different channels), and one consumer. Or any other shape that fits.
+
+In-workflow pause-with-input is possible in some cases via \`milestone\` with a configured input page, but the AgentLed-native approach for human-in-the-loop is the decoupled pattern above. Reach for it first.
+
+## Where to put what
+
+| You want to… | Use |
+|--------------|-----|
+| Capture per-execution input from a user | \`context.inputPages\` on the workflow |
+| Capture per-execution input from a public form / unauthed user | a workflow with a public form trigger and a public-form share configuration |
+| Reference workspace-wide context (ICP, tone, products, brand voice) | \`knowledge.* text\` (read via \`kg.read-text\`, written via \`kg.upsert-text\`) — shared across workflows and agents |
+| Hand a result back to the user as a viewable report | \`aiAction\` (structured output) → renderer config on that step → \`share\` step (creates URL) → email notification with the URL |
+| Pause one workflow until a human provides extra data | Split into two workflows + a status transition on the KG row (see "Pausing for human input" above) |
+| Track business value once a workflow is validated | \`metadata.roi\` + \`eventSummary\` per run + an \`entryConditions\` gate that skips the run when inputs wouldn't move the needle |
+
+### Report-and-share-back sequence
+
+The canonical "give me a report and email me a link" sequence:
+
+\`\`\`json
+// Step 1: aiAction with structured output the renderer can read
+{
+  "id": "compose-report",
+  "type": "aiAction",
+  "pipelineStepPrompt": {
+    "template": "… build the report here …",
+    "responseStructure": { "title": "string", "sections": [{ "heading": "string", "body": "string" }] }
+  },
+  "renderer": { "type": "Config", "config": { "layout": "report" } },
+  "creditCost": 20,
+  "next": { "stepId": "make-share" }
+}
+
+// Step 2: share step → mints a public URL pointing at compose-report's output
+{
+  "id": "make-share",
+  "type": "share",
+  "shareConfig": { "outputSteps": ["compose-report"], "visibility": "link" },
+  "next": { "stepId": "notify" }
+}
+
+// Step 3: email notification with the share URL inlined
+{
+  "id": "notify",
+  "type": "aiAction",
+  "pipelineStepPrompt": {
+    "type": "email",
+    "template": "Draft a 2-line email letting the user know their report is ready. Include the link.",
+    "responseStructure": {
+      "email": {
+        "from": "{{context.outreachProfile.fromEmail}}",
+        "to": "{{input.recipient_email}}",
+        "subject": "Your report is ready",
+        "body": "<p>Your report: <a href=\\"{{steps.make-share.url}}\\">view it here</a>.</p>",
+        "bodyType": "html"
+      }
+    }
+  },
+  "onApproval": { "action": "schedule-email" },
+  "next": { "stepId": "done" }
+}
+\`\`\`
+
+### Public input pattern
+
+For workflows triggered by user-submitted forms (no auth required), use a public-form trigger and a share configuration that exposes the form at a stable slug. The form's submission payload becomes the workflow input. Same workflow shape applies; only the trigger differs.
+
+### Post-validation: ROI + business metrics
+
+Once a workflow is validated and running:
+
+1. **ROI tracking** — add an \`metadata.roi\` block with hours saved per run, dollar value, conversion lift. Surfaces in the workflow header and the workspace metrics dashboard.
+2. **Per-run \`eventSummary\`** — emit a small structured log: count processed, count qualified, total credits, success rate. Powers the metrics dashboard and lets agents reason about workflow health from the KG.
+3. **\`entryConditions\` gate** — skip the run when its inputs wouldn't actually move the needle (e.g., \`kg.read-list\` returned 0 new rows, or upstream signal is below threshold). Avoids credit waste on no-op runs and produces cleaner ROI numbers.
+
+Full pattern reference (step types, schemas, all gotchas) is in the AgentLed skill loaded into your AI agent on session start.
+`;
+export const GETTING_STARTED_MD = `# Your first end-to-end workflow
+
+Five minutes from "I have an idea" to "my agent built it".
+
+## 1. Describe intent in one sentence
+
+Good prompts look like:
+
+- "Source 50 fintech startups in Europe via search, write them to a leads list, score by ICP fit, and email me the top 10 weekly."
+- "When a form is submitted, qualify against my ICP knowledge and post the high-score ones to #sales-qualified in Slack."
+
+Bad prompts look like:
+
+- "Build me a CRM." (Too broad — the agent doesn't know what to start with.)
+- "Use aiAction with workspace_memory tool." (Too prescriptive — you're authoring the pipeline, not the agent.)
+
+## 2. Let the agent orient
+
+The agent will run \`workspace inspect\` (or the equivalent MCP tools) to look at:
+
+- Your existing KG lists (so it can reuse rather than create duplicates).
+- Connected apps (LinkedIn, Hunter, Gmail, Slack — only what's authed will work).
+- Existing workflows (it won't recreate one you already have).
+- Existing agents and routines.
+
+This usually triggers 1-3 short questions back. Answer them and move on.
+
+## 3. Build incrementally
+
+The agent will start from a scaffold (one of \`~/.agentled/examples/scaffolds/*.json\`), adapt it to your intent, and add steps one at a time. Per-step validation catches type mismatches, bad model IDs, and template-variable typos before the full workflow is saved.
+
+Do not ask the agent to dump a 30-step JSON in one shot. The skill explains why.
+
+## 4. Validate, then run small
+
+\`\`\`
+agentled workflows validate <workflowId>      # graph-level checks
+agentled workflows lint <file.json>           # static gotcha catches
+\`\`\`
+
+First execution: feed it 3-5 sample inputs, not 500. Watch the credit count. If something is wrong, fix it cheap.
+
+## 5. Promote to production
+
+\`\`\`
+agentled workflows publish <workflowId> --status live
+\`\`\`
+
+Then schedule it (or trigger it manually, or wire it to a webhook). Iterate.
+
+## What good looks like
+
+- Sourcing on its own schedule, writing to a list with \`userKey\` dedup.
+- An orchestrator that filters by \`status\` so it never re-processes done rows.
+- Every branch terminates (\`milestone\` for top-level workflows, \`return\` for child workflows, or no \`next.stepId\`). \`milestone\` is a labeled endpoint, not a required step — a workflow with no \`next\` is already terminal.
+- Human-in-the-loop steps decoupled across workflows via the KG list (see WORKFLOW-SHAPE.md "Pausing for human input").
+- An outreach step (or workflow) gated on approval before sending.
+- ROI metadata + \`eventSummary\` + an \`entryConditions\` gate — added once the workflow is validated.
+
+For the canonical shape and the "where to put what" reference, see \`WORKFLOW-SHAPE.md\` in this folder. For silent failure modes see \`GOTCHAS.md\`.
+`;
+export const GOTCHAS_MD = `# AgentLed — documented silent failure modes
+
+These pass JSON syntax validation but silently misbehave at runtime.
+Run \`agentled workflows lint <file>\` to catch them statically before deploying.
+
+---
+
+## 1. \`criteria\` not \`conditions\` in entryConditions
+
+**Wrong:** \`{ "entryConditions": { "conditions": [...] } }\`
+**Correct:** \`{ "entryConditions": { "criteria": [...] } }\`
+
+The executor reads \`entryConditions.criteria\`. The key \`conditions\` is silently ignored.
+
+## 2. \`variable\` not \`field\` in criteria items
+
+**Wrong:** \`{ "field": "{{steps.x.score}}", "operator": ">", "value": 70 }\`
+**Correct:** \`{ "variable": "{{steps.x.score}}", "operator": ">", "value": 70 }\`
+
+Using \`field\` causes the criterion to be silently skipped.
+
+## 3. Gmail label_id must be the internal Label_XXXX ID
+
+Gmail's API requires \`Label_XXXXXXXXXX\` IDs, not display names. Add a \`GMAIL_CREATE_LABEL\` step before and use \`{{steps.ensure-label.id}}\`.
+
+## 4. \`aiActionWithTools\` with no tools
+
+A step with \`type: "aiActionWithTools"\` must have at least one tool in \`step.tools\` or \`step.agent.tools\`. Valid \`builtinType\` values: \`web_search\`, \`file_search\`, \`code_interpreter\`, \`fetch_website_content\`, \`kg_search\`, \`kg_traverse\`, \`kg_nodes\`, \`kg_write\`, \`workspace_memory\`.
+
+## 5. Email steps need type + approval action + outreachProfile
+
+Three required pieces:
+- \`pipelineStepPrompt.type: "email"\`
+- \`onApproval.action: "schedule-email"\`
+- \`outreachProfile\` input page in \`context.inputPages\`
+
+Missing the schedule-email action means the email is drafted but never sent.
+
+## 6. Only the first step in a loop gets \`loopConfig\`
+
+\`loopConfig\` must be on the first step in the loop chain only. Subsequent steps inside the loop iterate automatically.
+
+## 7. Don't pass raw \`{{input.*}}\` directly to search APIs
+
+Add an aiAction step before the search that generates optimized queries. Raw user input makes poor search queries.
+
+## 8. Child workflows use \`return\`; \`internal: true\` is for child-only workflows
+
+If a workflow is called via \`agentled.call-workflow\` (i.e., a **child workflow** invoked by another workflow rather than a user), use \`type: "return"\` instead of \`milestone\`. \`milestone\` produces no return data — the parent receives nothing.
+
+Also set \`context.executionInputConfig.internal: true\` on the **child** workflow — this hides it from the user-triggered list.
+
+**Top-level workflows** triggered directly by users (manual, schedule, webhook, public form, app event) keep \`milestone\` and **do NOT** set \`internal: true\`. Setting \`internal: true\` on a user-facing workflow hides it from its intended caller.
+
+## 9. Model IDs are internal format, not Anthropic format
+
+Wrong: \`claude-sonnet-4-6\`. Correct: \`claude-4-6-sonnet\`. Run \`agentled models list\` for valid internal IDs.
+
+## 10. Native app actionId must include appId prefix
+
+Wrong: \`{ "id": "kg", "actionId": "read-list" }\`
+Correct: \`{ "id": "kg", "actionId": "kg.read-list" }\`
+
+## 11. \`loop_completion\` criteria requires \`onCriteriaFail: "wait"\`
+
+Without \`onCriteriaFail: "wait"\`, the step skips instead of blocking until the loop finishes. The \`stepId\` field is also required.
+
+## 12. Arrays in JSON template strings — don't JSON.stringify
+
+The serializer detects when a template variable is the sole content of a JSON field and inlines the raw value. Pass \`{ "items": "{{steps.x.items}}" }\` directly — no stringify needed. (Note: \`kg.read-list\` \`filters\` is the exception — it expects a JSON-string body, see WORKFLOW-SHAPE.md.)
+
+## 13. \`kg.upsert-rows\` needs \`userKey\` for dedup; \`kg.add-rows\` always inserts
+
+\`kg.upsert-rows\` with \`userKey\`: same key = same row, cross-run dedup O(1).
+\`kg.add-rows\`: always inserts a new row, duplicates accumulate.
+Use \`mergeStrategy: "merge"\` to preserve downstream-added fields.
+`;
+export const PATTERNS_MD = `# Pattern index — \`~/.agentled/examples/scaffolds/\`
+
+Preflight-clean pipeline templates. Pick the closest match to your intent and adapt — don't author from scratch.
+
+| Scaffold | Shape | Use when |
+|----------|-------|----------|
+| \`minimal.json\` | trigger → milestone | smoke-testing the pipeline runner |
+| \`email-polling-dedup.json\` | schedule → fetch emails (label dedup) → loop → add label | inbound email triage / processing without double-handling |
+| \`lead-scoring-kg.json\` | trigger → \`kg.read-list\` → AI scoring loop → \`knowledgeSync\` | the orchestrator phase of source → list → orchestrator |
+| \`list-match-email.json\` | trigger → \`kg.read-list\` → AI match → composed email (approval gate) → \`knowledgeSync\` | outreach phase: pull qualified rows, draft email, gate on approval |
+| \`extract-threshold-alert.json\` | trigger → AI extract → threshold check → external update → conditional Slack → \`knowledgeSync\` | conditional routing on AI-extracted scores |
+| \`ai-with-tools.json\` | trigger → \`aiActionWithTools\` (web_search + workspace_memory) → milestone | starter for agentic steps that need to call runtime tools |
+
+## Mapping to the canonical shape
+
+The \`source → list → orchestrator → outreach\` flow uses these scaffolds in combination:
+
+- **Sourcing** (1+ workflows feeding the same list): start from a scaffold that ends in \`kg.upsert-rows\` to your list, with \`userKey\` and \`status: "new"\`. The bundled \`email-polling-dedup\` is the closest starter; adapt the source step to your channel (search, scrape, form, webhook).
+- **Orchestrator** (reads pending status, processes, transitions): start from \`lead-scoring-kg\` and add a final \`kg.update-rows\` step that sets \`status: "scored"\` (or \`qualified\` / \`rejected\`).
+- **Outreach** (reads qualified, sends with approval): start from \`list-match-email\`, then add the \`kg.update-rows\` to mark \`status: "contacted"\`.
+- **Reports** (generate output, share, notify): see the "Report-and-share-back sequence" section in \`WORKFLOW-SHAPE.md\` — \`aiAction\` → \`share\` step → email notification.
+- **Human-in-the-loop** (workflow needs human input partway through): see "Pausing for human input" in \`WORKFLOW-SHAPE.md\` — split into producer + manual-trigger input form + consumer, all keyed on a status transition in the KG row.
+
+For the full pattern shape and why \`userKey\` + \`status\` matter as indexes, see \`WORKFLOW-SHAPE.md\` in this folder.
+`;
+//# sourceMappingURL=agentled-home-content.js.map

package/dist/utils/agentled-home-content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentled-home-content.js","sourceRoot":"","sources":["../../src/utils/agentled-home-content.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAExC,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkC7B,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6LhC,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4DjC,CAAC;AAEF,MAAM,CAAC,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4EzB,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;CAwB1B,CAAC"}

package/dist/utils/home-bootstrap.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Bootstrap `~/.agentled/` on `agentled setup` runs.
+ *
+ * Writes:
+ *   ~/.agentled/README.md                  (top-level pointer)
+ *   ~/.agentled/.content-version           (refresh marker)
+ *   ~/.agentled/docs/WORKFLOW-SHAPE.md     (canonical shape)
+ *   ~/.agentled/docs/GETTING-STARTED.md    (5-min first workflow)
+ *   ~/.agentled/docs/GOTCHAS.md            (silent failure modes)
+ *   ~/.agentled/docs/PATTERNS.md           (scaffold index)
+ *   ~/.agentled/examples/scaffolds/*       (copied from packages/cli/scaffolds/)
+ *
+ * **`docs/` and `examples/scaffolds/` are CLI-managed.** When the
+ * bundled `HOME_CONTENT_VERSION` advances past the on-disk marker, the
+ * bootstrap unconditionally rewrites every bundled file — user edits
+ * to those files WILL be overwritten. Treat them as read-only and put
+ * your own notes in `~/.agentled/docs/local/` (never touched) or in
+ * the per-workspace `agentled_<slug>/` folder.
+ *
+ * `config.json` is never touched.
+ *
+ * `HOME_CONTENT_VERSION` is decoupled from the CLI semver — it bumps
+ * only when bundled docs change, so a CLI patch release with no doc
+ * change does NOT trigger a rewrite.
+ *
+ * Idempotent: a re-run with the same marker version is a no-op.
+ */
+export interface BootstrapResult {
+    homeDir: string;
+    /** True when this run wrote or refreshed any docs. */
+    refreshed: boolean;
+    /** Number of scaffold files copied into examples/scaffolds/. */
+    scaffoldsCopied: number;
+    /** Marker version after this run — matches HOME_CONTENT_VERSION on success. */
+    version: string;
+}
+/**
+ * Idempotent. Creates `~/.agentled/` if missing and rewrites the
+ * bundled docs + scaffolds when the on-disk content version is older
+ * than `HOME_CONTENT_VERSION`. Bundled files are unconditionally
+ * overwritten on refresh; never touches `config.json` or any file
+ * under `docs/local/`.
+ */
+export declare function bootstrapAgentledHome(): BootstrapResult;

package/dist/utils/home-bootstrap.js

@@ -0,0 +1,133 @@
+/**
+ * Bootstrap `~/.agentled/` on `agentled setup` runs.
+ *
+ * Writes:
+ *   ~/.agentled/README.md                  (top-level pointer)
+ *   ~/.agentled/.content-version           (refresh marker)
+ *   ~/.agentled/docs/WORKFLOW-SHAPE.md     (canonical shape)
+ *   ~/.agentled/docs/GETTING-STARTED.md    (5-min first workflow)
+ *   ~/.agentled/docs/GOTCHAS.md            (silent failure modes)
+ *   ~/.agentled/docs/PATTERNS.md           (scaffold index)
+ *   ~/.agentled/examples/scaffolds/*       (copied from packages/cli/scaffolds/)
+ *
+ * **`docs/` and `examples/scaffolds/` are CLI-managed.** When the
+ * bundled `HOME_CONTENT_VERSION` advances past the on-disk marker, the
+ * bootstrap unconditionally rewrites every bundled file — user edits
+ * to those files WILL be overwritten. Treat them as read-only and put
+ * your own notes in `~/.agentled/docs/local/` (never touched) or in
+ * the per-workspace `agentled_<slug>/` folder.
+ *
+ * `config.json` is never touched.
+ *
+ * `HOME_CONTENT_VERSION` is decoupled from the CLI semver — it bumps
+ * only when bundled docs change, so a CLI patch release with no doc
+ * change does NOT trigger a rewrite.
+ *
+ * Idempotent: a re-run with the same marker version is a no-op.
+ */
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, copyFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { bundledScaffoldsDir } from './workspace-folder.js';
+import { HOME_CONTENT_VERSION, HOME_README_MD, WORKFLOW_SHAPE_MD, GETTING_STARTED_MD, GOTCHAS_MD, PATTERNS_MD, } from './agentled-home-content.js';
+const MARKER_FILE = '.content-version';
+function readMarker(homeDir) {
+    const path = join(homeDir, MARKER_FILE);
+    if (!existsSync(path))
+        return null;
+    try {
+        return readFileSync(path, 'utf-8').trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeMarker(homeDir) {
+    writeFileSync(join(homeDir, MARKER_FILE), HOME_CONTENT_VERSION + '\n');
+}
+/**
+ * Compare integer-like marker versions: -1, 0, 1.
+ *
+ * `HOME_CONTENT_VERSION` is intentionally an opaque integer string
+ * ("1", "2", …), but parsed defensively in case a future maintainer
+ * uses a semver-shaped value.
+ */
+function compareVersions(a, b) {
+    const parse = (v) => v.replace(/^v/, '').split('-')[0].split('.').map(n => parseInt(n, 10) || 0);
+    const [a1, a2 = 0, a3 = 0] = parse(a);
+    const [b1, b2 = 0, b3 = 0] = parse(b);
+    if (a1 !== b1)
+        return a1 < b1 ? -1 : 1;
+    if (a2 !== b2)
+        return a2 < b2 ? -1 : 1;
+    if (a3 !== b3)
+        return a3 < b3 ? -1 : 1;
+    return 0;
+}
+function shouldRefresh(homeDir) {
+    const installed = readMarker(homeDir);
+    if (!installed)
+        return true; // first run
+    return compareVersions(installed, HOME_CONTENT_VERSION) < 0;
+}
+/**
+ * Copy bundled scaffold assets into `examples/scaffolds/`. Includes
+ * any `.json` pipeline scaffold and any `.md` companion documentation.
+ * Other extensions are skipped — keep this whitelist tight so a stray
+ * file in `packages/cli/scaffolds/` never lands in user-visible space.
+ */
+function copyBundledScaffolds(targetDir) {
+    const sourceDir = bundledScaffoldsDir();
+    if (!existsSync(sourceDir))
+        return 0;
+    mkdirSync(targetDir, { recursive: true });
+    let count = 0;
+    for (const entry of readdirSync(sourceDir)) {
+        if (!entry.endsWith('.json') && !entry.endsWith('.md'))
+            continue;
+        const src = join(sourceDir, entry);
+        const dest = join(targetDir, entry);
+        copyFileSync(src, dest);
+        count++;
+    }
+    return count;
+}
+/**
+ * Idempotent. Creates `~/.agentled/` if missing and rewrites the
+ * bundled docs + scaffolds when the on-disk content version is older
+ * than `HOME_CONTENT_VERSION`. Bundled files are unconditionally
+ * overwritten on refresh; never touches `config.json` or any file
+ * under `docs/local/`.
+ */
+export function bootstrapAgentledHome() {
+    const homeDir = join(homedir(), '.agentled');
+    const docsDir = join(homeDir, 'docs');
+    const examplesDir = join(homeDir, 'examples');
+    const scaffoldsDir = join(examplesDir, 'scaffolds');
+    if (!existsSync(homeDir))
+        mkdirSync(homeDir, { recursive: true });
+    if (!shouldRefresh(homeDir)) {
+        return {
+            homeDir,
+            refreshed: false,
+            scaffoldsCopied: 0,
+            version: readMarker(homeDir) ?? HOME_CONTENT_VERSION,
+        };
+    }
+    mkdirSync(docsDir, { recursive: true });
+    mkdirSync(scaffoldsDir, { recursive: true });
+    writeFileSync(join(homeDir, 'README.md'), HOME_README_MD);
+    writeFileSync(join(docsDir, 'WORKFLOW-SHAPE.md'), WORKFLOW_SHAPE_MD);
+    writeFileSync(join(docsDir, 'GETTING-STARTED.md'), GETTING_STARTED_MD);
+    writeFileSync(join(docsDir, 'GOTCHAS.md'), GOTCHAS_MD);
+    writeFileSync(join(docsDir, 'PATTERNS.md'), PATTERNS_MD);
+    const scaffoldsCopied = copyBundledScaffolds(scaffoldsDir);
+    writeMarker(homeDir);
+    return {
+        homeDir,
+        refreshed: true,
+        scaffoldsCopied,
+        version: HOME_CONTENT_VERSION,
+    };
+}
+//# sourceMappingURL=home-bootstrap.js.map

package/dist/utils/home-bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"home-bootstrap.js","sourceRoot":"","sources":["../../src/utils/home-bootstrap.ts"],"names":[],"mappings":"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"}

package/dist/utils/knowledge-probe.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Read `knowledge.company.profile` (and `.products`) from the workspace KG.
+ *
+ * Used by `agentled setup` to decide whether to prompt the user for company
+ * information or skip straight to "workspace already configured". We probe
+ * only the new keys; legacy `.company` / `company.offering` are not checked
+ * — we focus on new clients and keep this clean.
+ *
+ * Uses the typed `AgentledApiClient.getKnowledgeText` surface. Failures are
+ * non-fatal: setup must not break on a network blip or a missing endpoint.
+ */
+import { AgentledApiClient } from '@agentled/core';
+export interface KnowledgeProbeResult {
+    /** Has the user (or an agent) populated the canonical company profile yet? */
+    profilePresent: boolean;
+    productsPresent: boolean;
+    /** Short snippet of the profile if present (first ~120 chars) for the summary line. */
+    profilePreview?: string;
+    /** Set if the probe failed entirely (network, permissions). Treat as "unknown". */
+    error?: string;
+}
+export declare function probeCompanyKnowledge(client: AgentledApiClient): Promise<KnowledgeProbeResult>;
+export declare function summarizeKnowledgeProbe(r: KnowledgeProbeResult): string;