Packaged Factories

Discover, identify, and run first-party @you/* packaged factories with you run --named.

Discovery And Resolution

Choose a packaged factory when you want a catalog-backed named invocation by canonical name such as @you/goal. Use a project-local or saved named factory when you own the definition under a chosen root. Use --factory <factory.json> for a portable one-shot config path without guessing --dir. Invoke with you run --named <canonical-name>. Resolution order is project-local ./factory (or --dir), then global ~/.you-agent-factory/factories, then built-in catalog materialization on first use. On-disk scoped names are URL-encoded — for example ~/.you-agent-factory/factories/@you%2Ftts/.

Global shared factories root where packaged built-ins materialize:

~/.you-agent-factory/factories

The built-in catalog ships with the CLI. First use materializes an editable on-disk factory; later runs load that materialized copy under the resolved root instead of overwriting customer edits. Deep per-factory invocation signatures stay on packaged CLI topics such as you docs packaged-goal, you docs packaged-fusion, and you docs packaged-tts.

Factory Name Identity

The live FactoryName definition is the customer-facing identifier for one packaged or named factory. you run --named and factory-session lookup use that identity. Exhaustive Factory field inventories stay on the full schema and API reference pages.

FactoryName

string

Customer-facing identifier for one stored named factory. `GET /factory-sessions/~default/factory` may also return the reserved `UNDEFINED` identifier when the active runtime is still the default root factory and no durable current-factory pointer exists. Semantic validation failures return `INVALID_FACTORY_NAME`, including attempts to activate a named factory with the reserved identifier.

pattern^(UNDEFINED|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$
minLength1

Metadata And Source Fragments

The live Factory root contract carries free-form metadata for serialization and replay diagnostics, plus sourceDirectory and factoryDirectory provenance for the on-disk definition. Packaged materialization writes an editable factory under the resolved root; later runs load that copy instead of overwriting customer edits. This page does not invent auto-refresh or package-lock semantics. Open the full schema and API references when you need exhaustive contract lookup beyond these teaching embeds.

You Factory configuration

object

Top-level factory.json contract. Declare the work types, resources, portability resources, workers, and workstations that make up one authored factory here. Guarded loop breakers should be authored as guarded LOGICAL_MOVE workstations using VISIT_COUNT guards instead of a top-level exhaustion-rules field.

additionalPropertiesfalse (closed)

Fields

descriptiondescriptionOptionalNameValue
Optional localized customer-facing explanation of this Factory.
examplesexamplesOptionalFactoryInvocationExample[]
Ordered runnable invocation examples. Canonical Factory documents write examples here; legacy invocationSignature.examples are accepted only by the Factory input compatibility mapper.
factoryDirectoryfactoryDirectoryOptionalstring
Directory that contained the factory.json used for this serialized runtime config.
guardsguardsOptionalFactoryGuard[]
Root-level guards that apply across the factory instead of one specific workstation or input.
ididOptionalstring
Factory identifier used as the factory-level template context fallback.
inputTypesinputTypesOptionalInputType[]
Named input kinds accepted by the factory. The default input type is implicit and must not be declared.
invocationReturninvocationReturnOptionalInvocationReturn
Optional factory-authored invocation primary-result policy shared by CLI and API entrypoints. When omitted, runtimes use the SUBMITTED_WORK_TERMINAL fallback and return the first terminal content for the work item originally submitted by the invocation.
invocationSignatureinvocationSignatureOptionalFactoryInvocationSignature
Optional canonical callable argument contract shared by CLI, API, dashboard, docs, and packaged factories. When omitted, callers use the factory's compatibility invocation behavior.
layoutlayoutOptionalFactoryLayout
Optional non-executable graph editor layout metadata keyed by canonical graph node and edge ids.
metadatametadataOptionalStringMap
Free-form factory-level metadata carried through runtime serialization and replay diagnostics.
namenameRequiredFactoryName
orchestratororchestratorOptionalFactoryOrchestrator
Authored orchestrator identity for this factory. When omitted, existing Petri factories load through compatibility defaulting to orchestrator.kind = PETRI.
resourcesresourcesOptionalResource[]
Shared capacity pools that workers or workstations can consume while work is executing.
runnerrunnerOptionalRunnerID
Default runner selection for the factory when a workstation does not declare its own runner override.
sourceDirectorysourceDirectoryOptionalstring
Original source directory for record/replay and drift diagnostics.
supportingFilessupportingFilesOptionalResourceManifest
Optional portability manifest for validation-only external tools and portable bundled files. During v1 factory sharing, bundled INPUT files represent a share-time snapshot of the source factory's current inputs work so recipients restore detached starter-work copies that no longer sync back to the original factory. This contract is distinct from runtime-capacity resources.
versionversionOptionalHybridLogicalTimestamp
Server-managed current-factory version metadata. Clients should echo this value on complete replacement saves when they want stale-write detection, but durable factory configuration does not treat it as customer-authored topology.
workTypesworkTypesOptionalWorkType[]
Customer-authored work item categories and the lifecycle states each one can occupy.
workersworkersOptionalWorker[]
Reusable worker definitions that workstations reference by name when dispatching work.
workstationsworkstationsOptionalWorkstation[]
Processing steps that consume work, invoke workers, and emit the next work states.

Teaching embeds show the live Factory name plus metadata and source provenance fields that matter for packaged identity and materialization. They are not a substitute for the full schema or API inventories.

Full Factory schema

How To Use

Run a packaged factory by its canonical name with you run --named. Pass one-shot invocation text when the factory accepts shared DEFAULT handling. Inspect factory-defined arguments with you run --named <canonical-name> --help. Open packaged CLI topics such as you docs packaged-goal when you need per-factory invocation signatures. Use the factories configuration and global-configuration pages when you need factory.json topology or operator defaults instead of packaged discovery.

Run the packaged goal factory with one-shot invocation text:

you run --named @you/goal "Ship the login bug fix"

Run the packaged text-to-speech factory:

you run --named @you/tts "hi there"

Inspect factory-defined arguments for a packaged name:

you run --named @you/goal --help

Replace @you/goal or @you/tts with another packaged canonical name when you need that built-in.

Limits And Assumptions

This page is the web reference for first-party @you/* packaged factories. It is not a sync of packaged CLI markdown, not operator-defaults depth, not factory.json topology, and not a per-factory invocation-signature deep dive. Sibling factories and documentation links aid discovery only. Exhaustive metadata, sourceDirectory, and Factory field inventories live on the schema and API reference pages linked from the schema sections.