{"record":{"id":"3c8e9b5720330006","repo":"heygen-com/hyperframes","slug":"example-type","errorCode":"example-type","errorMessage":"\"${item.name}\" is an example — use `hyperframes init <dir> --example ${item.name}` instead.","messagePattern":"\"(.+?)\" is an example — use `hyperframes init <dir> --example (.+?)` instead\\.","errorType":"validation","errorClass":"AddError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/add.ts","lineNumber":227,"sourceCode":"    writeProjectConfig(projectDir, DEFAULT_PROJECT_CONFIG);\n    config = DEFAULT_PROJECT_CONFIG;\n  }\n\n  // 2. Resolve the requested item and its transitive registryDependencies.\n  //    The list comes back topologically sorted: dependencies first, the\n  //    requested item last.\n  let resolved: RegistryItem[];\n  try {\n    resolved = await resolveItemWithDependencies(opts.name, { baseUrl: config.registry });\n  } catch (err) {\n    throw new AddError(err instanceof Error ? err.message : String(err), \"unknown-item\");\n  }\n  // `resolveItemWithDependencies` always pushes the requested item last (or throws),\n  // so the final element is the item the user asked for.\n  const item = resolved[resolved.length - 1]!;\n\n  if (item.type === \"hyperframes:example\") {\n    throw new AddError(\n      `\"${item.name}\" is an example — use \\`hyperframes init <dir> --example ${item.name}\\` instead.`,\n      \"example-type\",\n    );\n  }\n\n  // 3. Compatibility-gate every item we're about to install (dependencies\n  //    included) before writing anything.\n  const warnings = assertCompatibleOrThrow(resolved, opts.cliVersion);\n\n  // 4. Remap targets per project config — each item by its own type.\n  const installPlan: RegistryItem[] = resolved.map((resolvedItem) => ({\n    ...resolvedItem,\n    files: resolvedItem.files.map((f) => ({\n      ...f,\n      target: remapTarget(resolvedItem, f.target, config.paths),\n    })),\n  }));\n","sourceCodeStart":209,"sourceCodeEnd":245,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/add.ts#L209-L245","documentation":"AddError with code 'example-type', thrown after resolution when the requested item's type is 'hyperframes:example'. Examples are full starter projects, not installable blocks/components, so the CLI refuses to add() them and points the user at `hyperframes init <dir> --example <name>`. This guard runs after resolution but before compatibility gating and install.","triggerScenarios":"Calling `hyperframes add <example-name>` where the resolved item is typed as an example (e.g. one of the entries under registry/examples). The message names the example and gives the exact init command to use instead.","commonSituations":"A user finds a starter in the catalog and runs `add` by reflex; tooling auto-discovers items and dispatches the wrong verb; copy-pasting an `add` command from docs that were describing an example.","solutions":["Use the command the error prints: `hyperframes init <dir> --example <item.name>`.","If you actually wanted a block or component with a similar name, search the catalog for the non-example item.","Update any automation that dispatched `add` on an example to branch on item type first."],"exampleFix":"# before: examples are not add-able\n$ hyperframes add starter-sizzle\n\n# after: init a new project from the example\n$ hyperframes init ./my-video --example starter-sizzle","handlingStrategy":"validation","validationCode":"// Pre-check: branch on item type before choosing add vs init\nif (item.type === 'hyperframes:example') {\n  throw new Error(`Use: hyperframes init <dir> --example ${item.name}`);\n}","typeGuard":"function isExampleItem(item: RegistryItem): boolean {\n  return item.type === 'hyperframes:example';\n}","tryCatchPattern":"try {\n  await runAdd(opts);\n} catch (err) {\n  if (err instanceof AddError && err.code === 'example-type') {\n    // switch to `hyperframes init <dir> --example <name>`\n  }\n}","preventionTips":["Reserve `add` for blocks and components; use `init` for example starters.","When automating discovery, branch on item.type before dispatching the verb."],"tags":["cli","registry","example","usage"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}