@agentled/cli/skills/agentled/references/workspace-folder.md

CLI for Agentled — manage workflows, apps, and knowledge from the command line. Zero context-window cost for AI agents.

# Local Workspace Folder & Workspace Surfaces

> Loaded on demand from the Agentled skill. Read this when a task spans more
> than a single tool call and produces local artifacts (drafts, decisions,
> debug bundles), or when seeding a templated workspace's sidebar/home.

## Local Workspace Folder — `agentled_<workspace-slug>/`

When working on Agentled tasks for a user (sourcing kits, workflow design, debugging executions, anything that spans more than a single tool call), **organize all local artifacts under a per-workspace folder named `agentled_<workspace-slug>/`** in the user's current working directory. The slug comes from the active workspace alias (e.g. `agentled_acme/`, `agentled_my-company/`) so a user with multiple workspaces never mixes their data. Resolve the slug from `agentled auth current` (use the alias if set, otherwise the workspace ID). Create the folder on first use; never scatter notes, JSON drafts, or transcripts at the repo root or under a generic `agentled_workspace/` name.

**Required structure (replace `<slug>` with the actual workspace slug):**

```
agentled_<slug>/
  README.md                 # what this folder is, current active workspace, last sync to KG
  decisions/                # one file per non-trivial decision (theme, schema, source list, etc.)
    YYYY-MM-DD-<slug>.md    # context · options considered · decision · rationale · revisit-when
  workflows/                # local drafts and copies of pipeline JSON before push
    <workflow-id>.json      # snapshot of the live workflow (use get_workflow → write file)
    <slug>.draft.json       # work-in-progress before create_workflow
  groups/                   # WorkflowGroup specs (see WG-001) — one file per group
    <group-slug>.kit.json
  kg/                       # local mirrors / drafts of KG content
    lists/<listKey>.schema.json
    text/<key>.md           # workspace company profile, theme docs, etc., before upserting
  executions/               # debug bundles for failed runs
    <executionId>/timeline.json, step-outputs/, notes.md
  worklog.md                # append-only chronological log of what was done, in 1-2 lines per entry
```

**Why a local folder at all when the KG already stores state?**
- KG is *workspace truth* — durable, structured, queryable. The local folder is *agent scratch* — drafts, decision rationale, raw debug data, transcripts. Mixing them pollutes the KG and loses local iteration history.
- Decisions ("we chose theme X for next edition", "we picked OpenVC + Crunchbase as initial sources") need a paper trail with reasoning. KG entries should carry the *outcome*, not the deliberation.
- Workflow drafts often go through 3-5 iterations before push — keep them local until ready.

**Sync rule:** at the end of any meaningful working session — and explicitly when the user says "save", "wrap up", "we're done for now" — summarize what's *durable and reusable* (final decisions, current themes, active sources, workflow purpose statements) and write it to the workspace KG via `upsert_knowledge_text` (for narrative docs) or `upsert_knowledge_rows` (for structured data). Use stable, predictable keys: `decisions.current-theme`, `groups.<slug>.spec`, `workflows.<id>.purpose`. For any group of workflows that forms a client-facing workspace pipeline, also create or update a client-readable KG text guide such as `<workspace-or-pipeline>.design`, `groups.<slug>.guide`, or `pipelines.<slug>.design`. Put the client explanation first (what it does, how it works, where data comes from, how approvals/sync/reporting work), then put workflow IDs, caveats, and debug details under "Operator Notes." Append a one-line entry to `worklog.md` recording what was synced and when.

**Worksession feedback:** in the final user-facing wrap-up for each meaningful working session, include a concise retrospective: what worked, what did not work or blocked progress, concrete improvements for the next session, and any follow-up risks. If the feedback is about Agentled itself — CLI behavior, MCP tools, workflow validation, app integrations, docs, missing capabilities, confusing errors, or platform behavior — send it to the Agentled team with the `submit_feedback_to_agentled` MCP tool when available. From the CLI, use `agentled feedback submit --type <bug|feature_request|escalation|ask> --title "<title>" --description "<details>"`.

**Don't sync:** raw debug bundles, full execution timelines, abandoned drafts, transcripts. Those stay local. Sync only what a future session — or another agent — will actually need to pick up the work.

**On session start:** if `agentled_<slug>/` for the active workspace already exists, read `README.md` and the most recent `decisions/` and `worklog.md` entries before proposing anything new. If it doesn't exist, ask the user once whether they want you to create it for this project, then proceed. If the user has multiple workspaces, only act on the folder matching the currently active workspace from `agentled auth current` — never operate on a sibling folder.

## Workspace Surfaces

The workspace home and sidebar carry workspace-level UI state on `Workspace.metadata`. These surfaces are read-only via the MCP today (most tooling does not need to write them), but agents authoring templated workspaces should know they exist:

### Pinned outputs (sidebar shortcuts)

`Workspace.metadata.pinnedOutputs[]` lists output pages that appear in the sidebar **after Knowledge & Data**, always visible regardless of which workflow is currently open. Operators set these manually from each output page's configuration sheet (toggle: *"Pin to workspace home"*). Pin sparingly: only pin output pages that are useful as direct workspace-level destinations, such as a recurring report, scoring dashboard, or canonical results list. Do not pin every output page, implementation detail, approval surface, or one-off execution artifact; normal workflow output pages remain accessible from the workflow itself. Each entry:

```json
{
  "pipelineId": "wfl_abc123",
  "pipelinePathname": "deal-flow",
  "outputPagePathname": "weekly-report",
  "label": "Weekly Investor Report",
  "iconName": "FileText",
  "pipelineName": "Deal Sourcing",
  "colorTextClass": "text-emerald-700 dark:text-emerald-400",
  "pinnedAt": "2026-05-09T10:00:00Z"
}
```

All snapshot fields capture the source values at pin time and do not auto-update if the workflow or page is later renamed or restyled. To refresh, the operator unpins and re-pins.

Sidebar rendering uses each field directly:
- `label` is the primary line.
- `pipelineName` renders in small muted text below the label, so two pins with the same `label` from different workflows are distinguishable.
- `iconName` resolves to a lucide icon (defaults to `Pin` if missing or unknown).
- `colorTextClass` is applied as a Tailwind class on the icon, mirroring the source workflow's accent. Use the same shape produced by the workflow style picker (e.g. `text-emerald-700 dark:text-emerald-400`).
- The pin row renders as **active** when the operator's current URL matches the pin's target.

When seeding a workspace via templates, pre-populate `pinnedOutputs[]` only for the curated artifacts the operator should access directly from the workspace sidebar on day one. Supply `pipelineName` and `colorTextClass` for the proper rendering (otherwise they fall back to the muted default, which still works but loses the visual cue). Pin entries reference output pages that exist on workflows in the same workspace; entries pointing at deleted or renamed pipelines still render — the URL just resolves to a 404 page until the pin is removed.