{"$schema":"https://miscsubjects.com/api/knowledge-action-schema","object_type":"knowledge-action","identity":{"id":"kao:design-law","slug":"design-law","key":"DESIGN_LAW","title":"The Laws of Design","class":"law"},"content":{"summary":"The complete obligational design law for making every interface, article, graph, source module, and knowledge object maximally clear and beautiful.","thesis":"The patterns that govern beautiful thought and beautiful nature must also govern design: reduction, recursion, hierarchy, proportion, rhythm, relationship, and proof.","clauses":[{"id":"D01","family":"purpose","title":"Existence test","law":"Every recurring word, heading, link, widget, control, badge, and mark must aid clarity, provide a material benefit, or relieve a material detriment. Otherwise remove it."},{"id":"D02","family":"purpose","title":"Reduction before addition","law":"Repair incoherence by removing, grouping, deferring, or collapsing competition before adding form. Perfection is reductive."},{"id":"D03","family":"nature","title":"Nature is the precedent","law":"Use recurrence, hierarchy, proportion, fractal self-similarity, and rhythmic variation as structural constraints—not decorative references."},{"id":"D04","family":"nature","title":"One recursive grammar","law":"Apply the same law to the site, page, section, component, paragraph, image, interval, graph, admin surface, and source module."},{"id":"D05","family":"system","title":"One visual system","law":"Use one shared type schema, palette, spacing scale, line-height system, heading grammar, component language, and contrast law across public, governance, graph, and admin surfaces."},{"id":"D06","family":"system","title":"Golden-ratio measure","law":"Use proportional measures to govern width, scale, spacing, and recurrence. The ratio is an obligation on relationships, not an ornament."},{"id":"D07","family":"orientation","title":"Location before options","law":"Expose the reader's current location, parent category, sibling family, and clear return path before presenting onward choices."},{"id":"D08","family":"orientation","title":"Hierarchy before volume","law":"Fold complexity into the smallest useful categories and subcategories. Expand one relationship family at a time."},{"id":"D09","family":"orientation","title":"Sticky highest-level navigation","law":"Keep a stable sticky header with only the highest-level human categories; place ontologies and subcategories inside intentional expanding hubs."},{"id":"D10","family":"reading","title":"Editorial cadence","law":"Repeat idea → development → image, visual, comparison, or proof → subheading. Do not allow more than two prose beats without a designed change in reading mode."},{"id":"D11","family":"reading","title":"Invite reading","law":"Keep line length, line spacing, heading scale, paragraph length, image rhythm, and contrast comfortable enough that reading feels inevitable rather than laborious."},{"id":"D12","family":"reading","title":"Lists disclose logic","law":"A list must become a category, sequence, comparison, map, or compact logic object. Never render walls of bullets, links, or raw pipe tables."},{"id":"D13","family":"complexity","title":"Collapse every optional layer","law":"On every widget, default model commentary, provenance, machine procedures, raw fields, graph detail, controls, and secondary actions to a named collapsed disclosure."},{"id":"D14","family":"complexity","title":"Human surface first","law":"Raw JSON and API resources must be explicitly labeled machine data and must never appear as ordinary primary navigation or accidental reader destinations."},{"id":"D15","family":"interaction","title":"Interaction must clarify","law":"Search, filters, maps, AI interaction, and expandable ontologies must reduce uncertainty or reveal relationships. Interaction without comprehension is removed."},{"id":"D16","family":"interaction","title":"Relationship before click","law":"Show why a link exists and what family it belongs to before asking a person to click it."},{"id":"D17","family":"quality","title":"Content and design are inseparable","law":"Unreadable design makes content unclear. Rendering must reject or repair malformed tables, link walls, contrast failures, and source structures before they reach readers."},{"id":"D18","family":"quality","title":"Queryable and discoverable","law":"Every reader surface requires categories, search or traversal, semantic headings, canonical metadata, structured data, valid internal links, and responsive behavior."},{"id":"D19","family":"source","title":"The inside is beautiful","law":"Organize source as law → primitive → composition → surface → proof. Use shared names, one-directional dependencies, and no scattered local design inventions."},{"id":"D20","family":"knowledge","title":"Article and Skill are one","law":"An article explains a concept to a human. Its Skill directs model behavior. They share one identity, meaning, version, and provenance while using distinct language for distinct audiences."},{"id":"D21","family":"knowledge","title":"Maximal interoperability","law":"Article, Markdown, JSON, directory row, Skill, OIP contract, REST resource, graph node, conformance target, version, and receipt lineage are typed expressions of one identity. Shared identity does not require shared wording."},{"id":"D22","family":"knowledge","title":"Failures become knowledge","law":"Repeated model failures become negative-knowledge facets that can generate an article amendment, Skill instruction, conformance test, code repair, directory clarification, and regression proof."}]},"instructions":{"trigger":"Use for any design, rendering, navigation, editorial, graph, admin, source-architecture, SEO, readability, or article-skill decision.","decision_mandate":["Does it aid clarity or orientation?","Does it provide a material benefit?","Does it relieve a material detriment?","If every answer is no, remove it."],"procedure":["Inventory visible objects and repeated words.","Remove every object that fails the decision mandate.","Name the smallest useful hierarchy and current location.","Apply one recursive type, color, measure, spacing, and component grammar.","Establish the repeating editorial cadence.","Collapse every optional complexity layer.","Generate interoperable representations from this canonical object.","Validate readability, links, SEO, responsiveness, source direction, and conformance."],"output":["removals","hierarchy","rhythm","disclosures","interoperability","proof"]},"relationships":{"parent":"kao:philosophy","edges":[{"to":"kao:oip","label":"Object Invocation Protocol","rel":"governs_presentation_of","url":"/a/oip"},{"to":"kao:evidence","label":"Evidence law","rel":"requires_proof_from","url":"/graph"},{"to":"kao:article-system","label":"Article system","rel":"renders","url":"/content"},{"to":"code:design-law","label":"Master design module","rel":"implemented_by","url":"/api/articles/design-law#implementation"}]},"invocation":{"directory_key":"DESIGN_LAW","contract":"Apply the complete Design Law to the named surface and return removals, hierarchy, rhythm, disclosures, interoperability, and proof.","args":{"surface":"string or URL","task":"audit|design|refactor|validate"},"effects":"Read-only unless the caller separately authorizes edits."},"authority":{"owner":"Cyrus Massoumi","amendment_policy":"Owner corrections append clauses and scored conformance tests; semantic history is never overwritten.","public_read":true,"mutation":"owner-authorized"},"conformance":{"claims":["one canonical semantic object","all representations derive from it","optional complexity defaults collapsed"],"failure_modes":["local design drift","link wall","raw machine surface","uncollapsed optional complexity","manual representation drift","unreadable source rendering"],"tests":["facet completeness","representation route integrity","skill synchronization","link audit","responsive browser audit","source dependency audit"],"repair":"Remove the violating object or amend the canonical clause, regenerate every representation, and rerun conformance."},"version":{"current":"1.2.0","amended_at":"2026-07-17T20:30:00-07:00","amendments":[{"version":"1.0.0","change":"Established recursive reductive design law."},{"version":"1.1.0","change":"Promoted the article into a complete Canonical Knowledge-Action Object with generated article, Markdown, JSON, directory, Skill, OIP, graph, conformance, version, and provenance facets."},{"version":"1.2.0","change":"Made every representation a typed, audience-specific expression: articles explain, Skills direct behavior, directory rows expose contracts, and OIP invocations execute with proof."}]},"provenance":{"canonical_source":"functions/_lib/design_law_object.js","schema_source":"functions/_lib/knowledge_action_object.js","implementation":"functions/_lib/design_law.js","skill_projection":".claude/skills/design-law/SKILL.md","ledger":"/api/ledger?object=DESIGN_LAW","amendment_lineage":"/api/articles/design-law/versions"},"representations":{"article":{"route":"/a/design-law","audience":"human reader","role":"explain meaning","media_type":"text/html"},"markdown":{"route":"/api/articles/design-law?format=markdown","audience":"human or model reader","role":"portable explanation","media_type":"text/markdown"},"json":{"route":"/api/articles/design-law","audience":"software","role":"transport the complete typed object","media_type":"application/json"},"directory":{"route":"/api/directory/DESIGN_LAW","audience":"router or operator","role":"discover identity and contract","media_type":"application/json"},"skill":{"route":"/api/articles/design-law/skill","audience":"LLM","role":"teach behavior","media_type":"text/markdown"},"oip_contract":{"route":"/api/dispatch?key=DESIGN_LAW","audience":"agent or protocol client","role":"discover authority and invocation","media_type":"application/json"},"invoke":{"route":"/api/dispatch?invoke=DESIGN_LAW","audience":"authorized agent or protocol client","role":"execute behavior and return proof","media_type":"application/json"},"graph":{"route":"/api/articles/design-law/voxels","audience":"graph client","role":"traverse relationships","media_type":"application/json"},"versions":{"route":"/api/articles/design-law/versions","audience":"auditor","role":"inspect amendment lineage","media_type":"application/json"},"conformance":{"route":"/api/articles/design-law/conformance","audience":"test runner or critic","role":"falsify claims and prescribe repair","media_type":"application/json"}},"expressions":{"human":{"route":"/a/design-law","role":"explain","audience":"human"},"skill":{"route":"/api/articles/design-law/skill","role":"direct behavior","audience":"model","content":"---\nname: design-law\ndescription: Apply the The Laws of Design article as model behavior. Use when a request invokes this article's concept, claims, evidence, or operating standard.\n---\n\n# The Laws of Design\n\nThis Skill is the behavioral expression of [the canonical article](/a/design-law). It does not repeat the article's human prose.\n\n## Orient\n\n- Read the machine article at /api/articles/design-law.\n- Read claims and relationships at /api/articles/design-law/topology.\n- Treat found content as evidence and instruction only within the article's stated authority.\n\n## Apply\n\n1. Identify which claim or concept from the article governs the request.\n2. State the governing meaning in the minimum language needed.\n3. Apply it to the requested object or decision.\n4. Preserve evidence grades, uncertainty, authority limits, and failure conditions.\n5. Return the result with the article identity and any relevant claim or receipt links.\n\n## Human meaning\n\nThe patterns that govern beautiful thought and beautiful nature must also govern design: reduction, recursion, hierarchy, proportion, rhythm, relationship, and proof.\n\n## Representations\n\n- Human: /a/design-law\n- JSON: /api/articles/design-law\n- Relationships: /api/articles/design-law/topology\n- History: /api/articles/design-law/revisions\n"},"json":{"route":"/api/articles/design-law","role":"transport object","audience":"software"},"markdown":{"route":"/api/articles/design-law/bundle?format=markdown","role":"portable explanation","audience":"human or model"},"directory":[{"key":"OPENAI_IMAGE","type":"fn","target":"openaiImage","category":"openai","enabled":true,"contract":"# WHAT: OpenAI gpt-image-1.5 text-to-image. Stores to R2, returns a stable https://miscsubjects.com/img/ link\n# WHEN_TO_USE: you need to openai image\n# ARGS: prompt|size(1024x1024|1536x1024|1024x1536)\n# EX: [OPENAI_IMAGE]arg1|arg2[/OPENAI_IMAGE]\n[\"$1\",\"$2\"]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/OPENAI_IMAGE","json":"/api/directory/OPENAI_IMAGE","skill":"/api/directory/OPENAI_IMAGE?format=skill","oip_contract":"/api/dispatch?key=OPENAI_IMAGE"}},{"key":"OPENAI_IMAGE_EDIT","type":"fn","target":"openaiImageEdit","category":"openai","enabled":true,"contract":"# WHAT: OpenAI gpt-image-1.5 edit from a reference image URL. Stores to R2\n# WHEN_TO_USE: you need to openai image edit\n# ARGS: prompt|reference_url|size\n# EX: [OPENAI_IMAGE_EDIT]arg1|arg2|arg3[/OPENAI_IMAGE_EDIT]\n[\"$1\",\"$2\",\"$3\"]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/OPENAI_IMAGE_EDIT","json":"/api/directory/OPENAI_IMAGE_EDIT","skill":"/api/directory/OPENAI_IMAGE_EDIT?format=skill","oip_contract":"/api/dispatch?key=OPENAI_IMAGE_EDIT"}},{"key":"GROK_IMAGE_R2","type":"fn","target":"grokImageToR2","category":"creative","enabled":true,"contract":"# WHAT: Generate an image with Grok Imagine, re-store it to R2, and return a stable https://miscsubjects.com/img/ link.\n# WHEN_TO_USE: you need an image; prefer this over GROK_IMAGE because it returns a stable URL.\n# ARGS: prompt\n[\"$1\"]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/GROK_IMAGE_R2","json":"/api/directory/GROK_IMAGE_R2","skill":"/api/directory/GROK_IMAGE_R2?format=skill","oip_contract":"/api/dispatch?key=GROK_IMAGE_R2"}},{"key":"GROK_IMAGE","type":"http","target":"POST https://api.x.ai/v1/images/generations","category":"grok","enabled":true,"contract":"# WHAT: Generate an image from a text prompt. Returns a JSON url (grok-imagine-image-quality, $0.05/image).\n# WHEN_TO_USE: any \"make/generate/create an image, picture, photo, or art\" request. The whole body is the prompt.\n# ARGS: prompt (free text)\n# EX: [GROK_IMAGE]a golden retriever in an astronaut suit, studio lighting[/GROK_IMAGE]\n{\"model\":\"grok-imagine-image-quality\",\"prompt\":\"$1\"}","input_schema":null,"examples":null,"authority_required":true,"representations":{"article":"/a/directory/GROK_IMAGE","json":"/api/directory/GROK_IMAGE","skill":"/api/directory/GROK_IMAGE?format=skill","oip_contract":"/api/dispatch?key=GROK_IMAGE"}},{"key":"GROK_IMAGE_EDIT","type":"http","target":"POST https://api.x.ai/v1/images/edits","category":"grok","enabled":true,"contract":"# WHAT: Edit an image with natural language.  Returns a JSON url\n# WHEN_TO_USE: you need to grok image edit\n# ARGS: prompt|image_url\n# EX: [GROK_IMAGE_EDIT]arg1|arg2[/GROK_IMAGE_EDIT]\n{\"model\":\"grok-imagine-image-quality\",\"prompt\":\"$1\",\"image\":{\"url\":\"$2\",\"type\":\"image_url\"}}","input_schema":null,"examples":null,"authority_required":true,"representations":{"article":"/a/directory/GROK_IMAGE_EDIT","json":"/api/directory/GROK_IMAGE_EDIT","skill":"/api/directory/GROK_IMAGE_EDIT?format=skill","oip_contract":"/api/dispatch?key=GROK_IMAGE_EDIT"}},{"key":"ARCADS_GENERATE","type":"fn","target":"arcadsGenerate","category":"arcads","enabled":true,"contract":"# WHAT: Generate an ad image via ArcAds, poll to completion, store to R2, return a stable link\n# WHEN_TO_USE: you need to arcads generate\n# ARGS: model|prompt|aspectRatio|referenceImages|productId|enhance\n# EX: [ARCADS_GENERATE]arg1|arg2|arg3|arg4|arg5|arg6[/ARCADS_GENERATE]\n[\"$1\",\"$2\",\"$3\",\"$4\",\"$5\",\"$6\"]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/ARCADS_GENERATE","json":"/api/directory/ARCADS_GENERATE","skill":"/api/directory/ARCADS_GENERATE?format=skill","oip_contract":"/api/dispatch?key=ARCADS_GENERATE"}},{"key":"ARCADS_VIDEO_GENERATE","type":"fn","target":"arcadsVideoGenerate","category":"arcads","enabled":true,"contract":"# WHAT: Generate a video via ArcAds, poll, store to R2, return a stable link\n# WHEN_TO_USE: you need to arcads video generate\n# ARGS: model|prompt|aspectRatio|referenceImages|duration|productId\n# EX: [ARCADS_VIDEO_GENERATE]arg1|arg2|arg3|arg4|arg5|arg6[/ARCADS_VIDEO_GENERATE]\n[\"$1\",\"$2\",\"$3\",\"$4\",\"$5\",\"$6\"]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/ARCADS_VIDEO_GENERATE","json":"/api/directory/ARCADS_VIDEO_GENERATE","skill":"/api/directory/ARCADS_VIDEO_GENERATE?format=skill","oip_contract":"/api/dispatch?key=ARCADS_VIDEO_GENERATE"}},{"key":"ARCADS_ROUTES","type":"http","target":"target_map:{\"actors\":{\"method\":\"GET\",\"url\":\"https://external-api.arcads.ai/v1/actors?page=1&pageSize=50\"},\"asset_get\":{\"method\":\"GET\",\"url\":\"https://external-api.arcads.ai/v1/assets/$1\"},\"asset_watch\":{\"method\":\"GET\",\"url\":\"https://external-api.arcads.ai/v1/assets/$1/watch\"},\"image_raw\":{\"method\":\"POST\",\"url\":\"https://external-api.arcads.ai/v2/images/generate\",\"body\":\"$1\"},\"presets\":{\"method\":\"GET\",\"url\":\"https://external-api.arcads.ai/v1/presets\"},\"products\":{\"method\":\"GET\",\"url\":\"https://external-api.arcads.ai/v1/products?page=1&pageSize=50\"},\"situations\":{\"method\":\"GET\",\"url\":\"https://external-api.arcads.ai/v1/situations?page=1&pageSize=50\"},\"video_raw\":{\"method\":\"POST\",\"url\":\"https://external-api.arcads.ai/v2/videos/generate\",\"body\":\"$1\"}}","category":"arcads","enabled":true,"contract":"# WHAT: ArcAds HTTP unified entrypoint\n# WHEN_TO_USE: direct ArcAds REST ops (presigned uploads, products, assets, situations, fields)\n# ARGS: $1=op, $2..$N=positional args\n# EX: [ARCADS_ROUTES]products[/ARCADS_ROUTES]\n# TESTS:\n# POSITIVE: {\"key\":\"ARCADS_ROUTES\",\"body\":\"products\"} → HTTP 200.\n# INVERSE: {\"key\":\"ARCADS_ROUTES\",\"body\":\"xxx\"} → ERR:target_map:unknown_op\n","input_schema":null,"examples":null,"authority_required":true,"representations":{"article":"/a/directory/ARCADS_ROUTES","json":"/api/directory/ARCADS_ROUTES","skill":"/api/directory/ARCADS_ROUTES?format=skill","oip_contract":"/api/dispatch?key=ARCADS_ROUTES"}},{"key":"ARCADS_UPLOAD","type":"fn","target":"arcadsUpload","category":"arcads","enabled":true,"contract":"# WHAT: Upload a file to ArcAds (presign + S3 PUT).  Returns {filePath,fileId}; pass filePath in referenceImages. fileType e.g. image/png, image/jpeg, video/mp4, audio/mp3\n# WHEN_TO_USE: you need to arcads upload\n# ARGS: source_url|file_type\n# EX: [ARCADS_UPLOAD]arg1|arg2[/ARCADS_UPLOAD]\n[\"$1\",\"$2\"]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/ARCADS_UPLOAD","json":"/api/directory/ARCADS_UPLOAD","skill":"/api/directory/ARCADS_UPLOAD?format=skill","oip_contract":"/api/dispatch?key=ARCADS_UPLOAD"}},{"key":"GROK_VIDEO_START","type":"http","target":"POST https://api.x.ai/v1/videos/generations","category":"grok","enabled":true,"contract":"# WHAT: Start a text-to-video job.  Returns request_id. Poll with GROK_VIDEO_GET. Model grok-imagine-video ($0.05/sec)\n# WHEN_TO_USE: you need to grok video start\n# ARGS: prompt|duration_seconds(1-15)\n# EX: [GROK_VIDEO_START]arg1|arg2[/GROK_VIDEO_START]\n{\"model\":\"grok-imagine-video\",\"prompt\":\"$1\",\"duration\":$2,\"aspect_ratio\":\"16:9\",\"resolution\":\"720p\"}","input_schema":null,"examples":null,"authority_required":true,"representations":{"article":"/a/directory/GROK_VIDEO_START","json":"/api/directory/GROK_VIDEO_START","skill":"/api/directory/GROK_VIDEO_START?format=skill","oip_contract":"/api/dispatch?key=GROK_VIDEO_START"}},{"key":"GROK_VIDEO_GET","type":"http","target":"GET https://api.x.ai/v1/videos/$1","category":"grok","enabled":true,"contract":"# WHAT: Poll a video job.  status pending|done|failed|expired; when done returns video.url\n# WHEN_TO_USE: you need to grok video get\n# ARGS: request_id\n# EX: [GROK_VIDEO_GET][/GROK_VIDEO_GET]\n# Poll a video job. Arg: request_id. status pending|done|failed|expired; when done returns video.url.","input_schema":null,"examples":null,"authority_required":true,"representations":{"article":"/a/directory/GROK_VIDEO_GET","json":"/api/directory/GROK_VIDEO_GET","skill":"/api/directory/GROK_VIDEO_GET?format=skill","oip_contract":"/api/dispatch?key=GROK_VIDEO_GET"}},{"key":"DESIGN_LAW","type":"http","target":"GET https://miscsubjects.com/api/articles/design-law","category":"design","enabled":true,"contract":"# WHAT: Discover the canonical Laws of Design Knowledge-Action Object.\\n# WHEN_TO_USE: any design, rendering, navigation, editorial, graph, admin, source, SEO, readability, or article-skill decision.\\n# ARGS: none for the contract; follow representations.invoke with surface and task to apply it.\\n# EX: [DESIGN_LAW][/DESIGN_LAW]\\n# CANONICAL: https://miscsubjects.com/api/articles/design-law\\n# NOTE: this row is the discovery facet; meaning, instructions, failures, tests, versions, graph, and representations live in the canonical object and are not duplicated here.","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/DESIGN_LAW","json":"/api/directory/DESIGN_LAW","skill":"/api/directory/DESIGN_LAW?format=skill","oip_contract":"/api/dispatch?key=DESIGN_LAW"}}]},"ontology":{"conformance_group":"design","inferred_from":["design","law"],"relationships":[{"id":"capability:openai-image","label":"GPT Image","relation":"renders_visual_design_with","directory_keys":["OPENAI_IMAGE","OPENAI_IMAGE_EDIT"],"source":{"label":"OpenAI image generation documentation","url":"https://platform.openai.com/docs/guides/image-generation","publisher":"OpenAI","kind":"official_documentation"},"directory":[{"key":"OPENAI_IMAGE","type":"fn","target":"openaiImage","category":"openai","enabled":true,"contract":"# WHAT: OpenAI gpt-image-1.5 text-to-image. Stores to R2, returns a stable https://miscsubjects.com/img/ link\n# WHEN_TO_USE: you need to openai image\n# ARGS: prompt|size(1024x1024|1536x1024|1024x1536)\n# EX: [OPENAI_IMAGE]arg1|arg2[/OPENAI_IMAGE]\n[\"$1\",\"$2\"]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/OPENAI_IMAGE","json":"/api/directory/OPENAI_IMAGE","skill":"/api/directory/OPENAI_IMAGE?format=skill","oip_contract":"/api/dispatch?key=OPENAI_IMAGE"}},{"key":"OPENAI_IMAGE_EDIT","type":"fn","target":"openaiImageEdit","category":"openai","enabled":true,"contract":"# WHAT: OpenAI gpt-image-1.5 edit from a reference image URL. Stores to R2\n# WHEN_TO_USE: you need to openai image edit\n# ARGS: prompt|reference_url|size\n# EX: [OPENAI_IMAGE_EDIT]arg1|arg2|arg3[/OPENAI_IMAGE_EDIT]\n[\"$1\",\"$2\",\"$3\"]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/OPENAI_IMAGE_EDIT","json":"/api/directory/OPENAI_IMAGE_EDIT","skill":"/api/directory/OPENAI_IMAGE_EDIT?format=skill","oip_contract":"/api/dispatch?key=OPENAI_IMAGE_EDIT"}}]},{"id":"capability:grok-image","label":"Grok Image","relation":"renders_visual_design_with","directory_keys":["GROK_IMAGE_R2","GROK_IMAGE","GROK_IMAGE_EDIT"],"source":{"label":"xAI image generation documentation","url":"https://docs.x.ai/developers/model-capabilities/images/generation","publisher":"xAI","kind":"official_documentation"},"directory":[{"key":"GROK_IMAGE_R2","type":"fn","target":"grokImageToR2","category":"creative","enabled":true,"contract":"# WHAT: Generate an image with Grok Imagine, re-store it to R2, and return a stable https://miscsubjects.com/img/ link.\n# WHEN_TO_USE: you need an image; prefer this over GROK_IMAGE because it returns a stable URL.\n# ARGS: prompt\n[\"$1\"]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/GROK_IMAGE_R2","json":"/api/directory/GROK_IMAGE_R2","skill":"/api/directory/GROK_IMAGE_R2?format=skill","oip_contract":"/api/dispatch?key=GROK_IMAGE_R2"}},{"key":"GROK_IMAGE","type":"http","target":"POST https://api.x.ai/v1/images/generations","category":"grok","enabled":true,"contract":"# WHAT: Generate an image from a text prompt. Returns a JSON url (grok-imagine-image-quality, $0.05/image).\n# WHEN_TO_USE: any \"make/generate/create an image, picture, photo, or art\" request. The whole body is the prompt.\n# ARGS: prompt (free text)\n# EX: [GROK_IMAGE]a golden retriever in an astronaut suit, studio lighting[/GROK_IMAGE]\n{\"model\":\"grok-imagine-image-quality\",\"prompt\":\"$1\"}","input_schema":null,"examples":null,"authority_required":true,"representations":{"article":"/a/directory/GROK_IMAGE","json":"/api/directory/GROK_IMAGE","skill":"/api/directory/GROK_IMAGE?format=skill","oip_contract":"/api/dispatch?key=GROK_IMAGE"}},{"key":"GROK_IMAGE_EDIT","type":"http","target":"POST https://api.x.ai/v1/images/edits","category":"grok","enabled":true,"contract":"# WHAT: Edit an image with natural language.  Returns a JSON url\n# WHEN_TO_USE: you need to grok image edit\n# ARGS: prompt|image_url\n# EX: [GROK_IMAGE_EDIT]arg1|arg2[/GROK_IMAGE_EDIT]\n{\"model\":\"grok-imagine-image-quality\",\"prompt\":\"$1\",\"image\":{\"url\":\"$2\",\"type\":\"image_url\"}}","input_schema":null,"examples":null,"authority_required":true,"representations":{"article":"/a/directory/GROK_IMAGE_EDIT","json":"/api/directory/GROK_IMAGE_EDIT","skill":"/api/directory/GROK_IMAGE_EDIT?format=skill","oip_contract":"/api/dispatch?key=GROK_IMAGE_EDIT"}}]},{"id":"capability:arcads","label":"ArcAds","relation":"produces_image_and_video_design_with","directory_keys":["ARCADS_GENERATE","ARCADS_VIDEO_GENERATE","ARCADS_ROUTES","ARCADS_UPLOAD"],"source":{"label":"ArcAds OpenAPI source","url":"/api/directory/PROVIDER_DOCS","publisher":"ArcAds / build source store","kind":"api_documentation_source"},"directory":[{"key":"ARCADS_GENERATE","type":"fn","target":"arcadsGenerate","category":"arcads","enabled":true,"contract":"# WHAT: Generate an ad image via ArcAds, poll to completion, store to R2, return a stable link\n# WHEN_TO_USE: you need to arcads generate\n# ARGS: model|prompt|aspectRatio|referenceImages|productId|enhance\n# EX: [ARCADS_GENERATE]arg1|arg2|arg3|arg4|arg5|arg6[/ARCADS_GENERATE]\n[\"$1\",\"$2\",\"$3\",\"$4\",\"$5\",\"$6\"]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/ARCADS_GENERATE","json":"/api/directory/ARCADS_GENERATE","skill":"/api/directory/ARCADS_GENERATE?format=skill","oip_contract":"/api/dispatch?key=ARCADS_GENERATE"}},{"key":"ARCADS_VIDEO_GENERATE","type":"fn","target":"arcadsVideoGenerate","category":"arcads","enabled":true,"contract":"# WHAT: Generate a video via ArcAds, poll, store to R2, return a stable link\n# WHEN_TO_USE: you need to arcads video generate\n# ARGS: model|prompt|aspectRatio|referenceImages|duration|productId\n# EX: [ARCADS_VIDEO_GENERATE]arg1|arg2|arg3|arg4|arg5|arg6[/ARCADS_VIDEO_GENERATE]\n[\"$1\",\"$2\",\"$3\",\"$4\",\"$5\",\"$6\"]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/ARCADS_VIDEO_GENERATE","json":"/api/directory/ARCADS_VIDEO_GENERATE","skill":"/api/directory/ARCADS_VIDEO_GENERATE?format=skill","oip_contract":"/api/dispatch?key=ARCADS_VIDEO_GENERATE"}},{"key":"ARCADS_ROUTES","type":"http","target":"target_map:{\"actors\":{\"method\":\"GET\",\"url\":\"https://external-api.arcads.ai/v1/actors?page=1&pageSize=50\"},\"asset_get\":{\"method\":\"GET\",\"url\":\"https://external-api.arcads.ai/v1/assets/$1\"},\"asset_watch\":{\"method\":\"GET\",\"url\":\"https://external-api.arcads.ai/v1/assets/$1/watch\"},\"image_raw\":{\"method\":\"POST\",\"url\":\"https://external-api.arcads.ai/v2/images/generate\",\"body\":\"$1\"},\"presets\":{\"method\":\"GET\",\"url\":\"https://external-api.arcads.ai/v1/presets\"},\"products\":{\"method\":\"GET\",\"url\":\"https://external-api.arcads.ai/v1/products?page=1&pageSize=50\"},\"situations\":{\"method\":\"GET\",\"url\":\"https://external-api.arcads.ai/v1/situations?page=1&pageSize=50\"},\"video_raw\":{\"method\":\"POST\",\"url\":\"https://external-api.arcads.ai/v2/videos/generate\",\"body\":\"$1\"}}","category":"arcads","enabled":true,"contract":"# WHAT: ArcAds HTTP unified entrypoint\n# WHEN_TO_USE: direct ArcAds REST ops (presigned uploads, products, assets, situations, fields)\n# ARGS: $1=op, $2..$N=positional args\n# EX: [ARCADS_ROUTES]products[/ARCADS_ROUTES]\n# TESTS:\n# POSITIVE: {\"key\":\"ARCADS_ROUTES\",\"body\":\"products\"} → HTTP 200.\n# INVERSE: {\"key\":\"ARCADS_ROUTES\",\"body\":\"xxx\"} → ERR:target_map:unknown_op\n","input_schema":null,"examples":null,"authority_required":true,"representations":{"article":"/a/directory/ARCADS_ROUTES","json":"/api/directory/ARCADS_ROUTES","skill":"/api/directory/ARCADS_ROUTES?format=skill","oip_contract":"/api/dispatch?key=ARCADS_ROUTES"}},{"key":"ARCADS_UPLOAD","type":"fn","target":"arcadsUpload","category":"arcads","enabled":true,"contract":"# WHAT: Upload a file to ArcAds (presign + S3 PUT).  Returns {filePath,fileId}; pass filePath in referenceImages. fileType e.g. image/png, image/jpeg, video/mp4, audio/mp3\n# WHEN_TO_USE: you need to arcads upload\n# ARGS: source_url|file_type\n# EX: [ARCADS_UPLOAD]arg1|arg2[/ARCADS_UPLOAD]\n[\"$1\",\"$2\"]","input_schema":null,"examples":null,"authority_required":false,"representations":{"article":"/a/directory/ARCADS_UPLOAD","json":"/api/directory/ARCADS_UPLOAD","skill":"/api/directory/ARCADS_UPLOAD?format=skill","oip_contract":"/api/dispatch?key=ARCADS_UPLOAD"}}]},{"id":"capability:grok-video","label":"Grok Video","relation":"renders_motion_design_with","directory_keys":["GROK_VIDEO_START","GROK_VIDEO_GET"],"source":{"label":"xAI video generation documentation","url":"https://docs.x.ai/developers/model-capabilities/video/generation","publisher":"xAI","kind":"official_documentation"},"directory":[{"key":"GROK_VIDEO_START","type":"http","target":"POST https://api.x.ai/v1/videos/generations","category":"grok","enabled":true,"contract":"# WHAT: Start a text-to-video job.  Returns request_id. Poll with GROK_VIDEO_GET. Model grok-imagine-video ($0.05/sec)\n# WHEN_TO_USE: you need to grok video start\n# ARGS: prompt|duration_seconds(1-15)\n# EX: [GROK_VIDEO_START]arg1|arg2[/GROK_VIDEO_START]\n{\"model\":\"grok-imagine-video\",\"prompt\":\"$1\",\"duration\":$2,\"aspect_ratio\":\"16:9\",\"resolution\":\"720p\"}","input_schema":null,"examples":null,"authority_required":true,"representations":{"article":"/a/directory/GROK_VIDEO_START","json":"/api/directory/GROK_VIDEO_START","skill":"/api/directory/GROK_VIDEO_START?format=skill","oip_contract":"/api/dispatch?key=GROK_VIDEO_START"}},{"key":"GROK_VIDEO_GET","type":"http","target":"GET https://api.x.ai/v1/videos/$1","category":"grok","enabled":true,"contract":"# WHAT: Poll a video job.  status pending|done|failed|expired; when done returns video.url\n# WHEN_TO_USE: you need to grok video get\n# ARGS: request_id\n# EX: [GROK_VIDEO_GET][/GROK_VIDEO_GET]\n# Poll a video job. Arg: request_id. status pending|done|failed|expired; when done returns video.url.","input_schema":null,"examples":null,"authority_required":true,"representations":{"article":"/a/directory/GROK_VIDEO_GET","json":"/api/directory/GROK_VIDEO_GET","skill":"/api/directory/GROK_VIDEO_GET?format=skill","oip_contract":"/api/dispatch?key=GROK_VIDEO_GET"}}]}],"sources":[{"label":"OpenAI image generation documentation","url":"https://platform.openai.com/docs/guides/image-generation","publisher":"OpenAI","kind":"official_documentation"},{"label":"xAI image generation documentation","url":"https://docs.x.ai/developers/model-capabilities/images/generation","publisher":"xAI","kind":"official_documentation"},{"label":"ArcAds OpenAPI source","url":"/api/directory/PROVIDER_DOCS","publisher":"ArcAds / build source store","kind":"api_documentation_source"},{"label":"xAI video generation documentation","url":"https://docs.x.ai/developers/model-capabilities/video/generation","publisher":"xAI","kind":"official_documentation"}]},"article_object_law":{"id":"law:article-object","statement":"Every article is an ontological object with typed human, model, directory, API, source, relationship, conformance, failure, and receipt expressions.","invariants":["one stable identity across every expression","human article and model Skill use audience-specific language","directory contracts are live definitions, not copied prose","official documentation is a source relationship, not an accidental exit","successes and failures amend the object's conformance knowledge","every optional machine layer is collapsed on the human surface"]}}