Update to Forge

{
  "description": "Use Forge Projects (hosted, live React components, organized in collections with skills) through the Forge MCP. Use when the user mentions Forge, a Forge project or component, a Forge collection or kit, a ui8.dev page, or a forge.ui8.ai share link; when they want to find, preview, publish, remix or organize UI they keep in Forge; when they ask about feedback on a Forge project; and in a codebase before building a piece of UI they may already have in Forge. Not for general UI questions with no Forge workspace involved.",
  "included_files": [],
  "name": "forge-projects",
  "skill_md_contents": "---\nname: forge-projects\ndescription: Use Forge Projects (hosted, live React components, organized in collections with skills) through the Forge MCP. Use when the user mentions Forge, a Forge project or component, a Forge collection or kit, a ui8.dev page, or a forge.ui8.ai share link; when they want to find, preview, publish, remix or organize UI they keep in Forge; when they ask about feedback on a Forge project; and in a codebase before building a piece of UI they may already have in Forge. Not for general UI questions with no Forge workspace involved.\n---\n\n# Forge Projects\n\nA **project** is a small React app hosted in Forge Cloud: Vite-shaped,\npreviewed live at a URL, with one or more **components** (named entry files\nthat share every other file) and a **story** (the props and values its\ncontrols edit). One component is the project's **cover**: the one shown\nfirst, used for its preview image and opened by its share and publish links.\nProjects are filed in **collections**. A collection or a workspace carries\n**skills**: SKILL.md rules that say how its projects are meant to be used,\nand **files**: one tree of logos, PDFs, fonts or reference data. A\ncollection with only skills is a design system; one with only projects is a\nparts bin.\n\nThe tools still use the older names: a **fragment** is a project and a\n**variant** is a component. Call every tool and pass every argument exactly\nas named (`fragment_find`, `fragmentId`, `variant`, `fragment_save_variant`\nand so on), and say \"project\" and \"component\" to the user.\n\nThe Forge MCP's own instructions carry the must-know; `fragment_docs` is the\nfull reference (limits, tree rules, the story format, error codes). Read it\nwhen a detail here is not enough.\n\n## Where you are decides what you can do\n\n- **Codex, or any agent with a shell and a filesystem**: every flow below.\n- **ChatGPT (no local shell)**: find, preview, publish, feedback, organize,\n  remix and skills. Do not call `fragment_start_session` or `fragment_pull`\n  there: an edit session needs you to run its download and upload commands,\n  and a pull needs a codebase to write files into. When the user asks to\n  create or change a project's code in ChatGPT, say that it needs Codex or\n  another coding agent connected to Forge, and offer what you can do here\n  (find a similar project, preview it, remix it, or edit its description,\n  tags and component values).\n\n## Use a Forge project in the codebase you are in\n\nDo this before building any piece of UI the user might already keep in Forge.\n\n1. `fragment_find { intent, project? }`. Say what you are about to build in\n   your own words; pass `project` facts about the codebase (framework,\n   styling, dependencies) when you know them. Follow the `next` line it\n   returns.\n2. If `gate.fits` is false, nothing fits: build it yourself, still following\n   the `relevant` skills.\n3. `skill_get { skillId }` for every skill listed. Read them before touching\n   code: they hold the tokens, spacing, naming and what never to do.\n4. `fragment_pull { fragmentId, variant? }`. It returns the files inline (or a\n   tar URL and command for a large tree), signed asset URLs (curl them; they\n   expire in an hour), dependencies, the story and the governing skills.\n5. Adapt, do not paste: match the codebase's import aliases and styling\n   entry, wire props to the story's values, keep the kit's tokens. Put\n   `provenance.header` as the first line of the adapted entry file. If the\n   codebase keeps agent skills, write each pulled skill as its whole\n   `folder` at `folder.path` (`.agents/skills/<name>/`, named exactly the\n   skill): run `folder.tar.command` (it replaces the folder once the\n   download worked, so files a skill dropped do not linger), or write\n   `folder.markdown` as SKILL.md, curl each file url to its relative path\n   and `chmod +x` `scripts/`.\n6. Never write one skill over another. Skills that share a name come back\n   in `skillCollisions`, and a folder whose SKILL.md has no\n   `metadata.forge-skill-id`, or a different one, is another skill (or the\n   user's own): ask the user which to keep.\n\nA hit that belongs to a collection is usually one part of a kit:\n`fragment_collection_get { collectionId }` lists its siblings, which the same\nskills govern. A share link `/share/collection/<id>` names a collection; read\nit the same way.\n\nFind, pull and `fragment_collection_get` also list the **files** kept beside\nthe projects (`fileTrees`: paths, mime, size). They are context: read one\nwith `file_get` (text inline, or a signed url), write a whole tree to disk\nwith `files_pull`, search with `files_find`. A project never links to a\ncollection file — copy the file into the project when it needs one.\n`file_save` adds a file (inline, or through the upload url it answers\nwithout content).\n\n## Create or edit a project (needs a shell)\n\n1. Call `fragment_start_session` first, before drafting anything:\n   `{ fragmentId }` to edit, or `{ name, description, tags, collectionId? }`\n   to create. Give the user its `shellUrl` right away; that page shows the\n   live preview while you work.\n2. Run `download.command` (optional for a new project), edit under\n   `workdir`, then run `upload.command` exactly as returned.\n3. `fragment_submit { fragmentId, sessionId, deleted? }`. Only changed files\n   are written. Give the user `shellUrl`, never `previewUrl`.\n4. Check `fragment_feedback_list { fragmentId }` when you start and after you\n   submit.\n\nNever put file contents in a tool argument; no tool accepts them. The server\nowns `index.html`, `src/main.tsx`, `tsconfig.json`, `vite.config.*` and\nlockfiles and ignores them on upload. Components live at\n`src/variants/<slug>.tsx` with a default export; dependencies go in\n`package.json` (served through esm.sh; React is provided); Tailwind v4 goes in\n`index.css`. A session lasts a limited time: on `session_expired`, start a\nnew one.\n\nComponent metadata (name, story, values) is not code: change it with\n`fragment_save_variant`, which works in ChatGPT too.\nWhen the user asks for controls, or for something to be adjustable, make\neach one a prop with a sensible default and declare it in the component's\nstory with `fragment_save_variant`: never build a settings panel into the\ncomponent.\n\n## Preview\n\n`fragment_preview { fragmentId, variant? }` when the user wants to see a\nproject. In ChatGPT the result renders as a live preview card with a component\nswitcher and an \"Open in Forge\" button, so do not repeat the links under it.\nElsewhere, give the user `shellUrl`. The raw `url` is for your own checks\nonly; never hand it to the user.\n\n## Publish\n\n`fragment_publish { fragmentId, slug?, password? }` serves a pinned snapshot\nat `https://<slug>.ui8.dev/`; later edits stay private until the next\npublish. `fragment_set_password` changes the password on a live page without\nrepublishing; `fragment_unpublish` takes the page down and keeps the slug.\n\n## Feedback\n\nPeople leave comments, proposed style edits and screenshots on a project's\npreview. `fragment_feedback_list { fragmentId, status? }` returns the open\nitems with their anchors (selector, text, component chain) and threads.\nAnswer with `fragment_feedback_reply { fragmentId, feedbackId, body }`: short,\nsaying what you did or what you need. Mark an item handled with\n`fragment_feedback_resolve { fragmentId, feedbackId }` (`reopen: true` puts\nit back). Only resolve what was actually addressed.\n\n## Organize and remix\n\n- `fragment_list` returns projects (with description and tags) and\n  collections. Scan descriptions and tags to find the one the user means.\n- `fragment_collection_create`, `fragment_move`, `fragment_rename`,\n  `fragment_describe` and `fragment_set_default_variant` (which sets the\n  project's cover) keep a workspace tidy. Reuse an existing collection\n  before creating a near-duplicate.\n- `fragment_remix` copies one project into a workspace;\n  `fragment_collection_remix` copies a whole kit with its skills.\n- `skill_list`, `skill_get` and `skill_save` manage skills. A skill is a\n  folder: SKILL.md plus files under `scripts/`, `references/` and `assets/`\n  that it links to by relative path. `skill_get` answers SKILL.md as\n  `markdown` and every file (text inline, binary by url); `skill_save` takes `files` (`{ path, content }`\n  or `{ path, contentBase64 }`) and `removeFiles`. Write one when the user\n  states rules a kit must follow: a short, imperative SKILL.md naming what\n  never to do, with long reference material in `references/`.\n\n## Ask first\n\n`fragment_publish`, `fragment_unpublish`, `fragment_archive`, `skill_delete`\nand `fragment_collection_remix` need `confirm: true`. Without it the answer\nis `confirmation_required` with what will happen (for a collection remix,\nthe project count against the room left).\n\n- When the user's own message asks for exactly that action on a project\n  you can name (\"publish Hero Section at hero.ui8.dev\", \"unpublish the\n  pricing page\", \"archive the old pricing card\"), the request is their\n  agreement: pass `confirm: true` and report what happened.\n- Otherwise ask first: you inferred the step, the target is ambiguous, the\n  user asked for something Forge does differently (there is no permanent\n  delete, only archive), or it is a `skill_delete` or a\n  `fragment_collection_remix`. Call without `confirm`, show the user what\n  will happen, and retry with `confirm: true` only after they agree in this\n  conversation.\n\nArchiving is not permanent: `fragment_unarchive` brings a project back,\nwith its public page and share link, without confirmation. Say so when you\narchive.\n\nTreat these as changes the user should have asked for, too:\n`fragment_restore_revision`, `fragment_delete_variant`, `skill_restore`, and\nanything that overwrites a project's name, description or tags.\n\n## Errors\n\nTools answer structured codes. The common ones:\n\n- `org_choice_required`: the user belongs to several workspaces. Ask which\n  one, then retry with `orgId`.\n- `not_found` / `forbidden`: the id is wrong, or it belongs to a workspace\n  the user is not a member of. Say so plainly; do not guess other ids.\n- `revision_conflict`: someone else changed it. Refetch, then redo the change.\n- `quota_exceeded`: the workspace's plan limit; tell the user which limit.\n- `upload_missing`: run `upload.command` before submitting.\n\nA compile error or a missing import is not a tool error: it shows in the\npreview with its file, line and column.\n"
}