{ "schema": "kiwe.start.v1", "contractVersion": "7.26", "updated": "2026-08-23", "repository": "Museintel/kiwe", "productName": "SeamFlow", "flowName": "seamflow", "compatibilityNames": ["Kiwe Start", "kiwe_plan_flow"], "purpose": "Fast safe external-AI entrypoint and flow planner for browser AI, IDE AI, MCP clients, skill-capable agents, and Kiwe Companion-assisted Appsite workflows.", "architecture": { "seamflow": "External AI command-central flow for creating, rebuilding, auditing, fixing, and converting Seam Framework + Bricks-powered webpages, headers, footers, reusable templates, Framework profiles, dynamic intent, and accessibility artifacts.", "compilerAuthority": "SEAM Compiler 0.13.0 deterministically owns raw Bricks conversion and the optional one-pass Framework mode; browser AI does not author production Bricks JSON or Framework Profile data.", "stageBoundary": "Raw /convert /bricks is Framework-neutral. Optional /convert /bricks /seamframework is the preferred one-pass mode; /seamframework remains valid while raw evidence is retained. Framework mode emits one Framework Profile plus dependent templates. Accessibility is separate.", "kiweInternalAi": "Plugin-native Companion/Internal AI. It is WordPress-aware, Bricks-aware, bounded, token-saving, and can assist SeamFlow through /usecompanion, API, or MCP routes without dumping the whole plugin.", "currentLaunchScope": "Close Seam Framework and Bricks-powered webpages/header/footer/templates/accessibility first.", "nextPhase": "DSA/AppShell theme is part of SeamFlow but full DSA theme production hardening follows after page-builder flow testing passes.", "creativeAuthority": "No Kiwe aesthetic influence during /ideate. Conversion and Framework commands preserve/translate. Bare /accessibility alone has bounded design-aware authority: minimal evidence-backed repairs plus an intentional peer dark appearance while preserving the approved light design." }, "doNot": [ "Do not browse, clone, or inspect the whole repository for startup.", "Do not search GitHub for hidden contracts.", "Do not use general web search, arXiv, unrelated GitHub search, commit browsing, stale local examples, prior-output research, or prior accepted notes to complete SeamFlow.", "Do not use search results when an exact raw URL/context route is required. If your environment starts a search instead of direct raw fetch/open, stop with ERROR: KIWE_SEARCH_DRIFT.", "Before every /command, including the first command after Start classification, fetch fresh discovery from https://start.kiwelaunch.com/.well-known/kiwe.json with a new refresh nonce, then use its content-hash immutable command route and pinned resources. Never execute from a URL or command context already used earlier in the conversation.", "Do not mark artifact lanes PASS from manual confidence, copied validator logic, reconstructed validator logic, simulated validator logic, or equivalent checks. PASS requires executable validator proof.", "Do not create docs, reports, ZIP files, duplicate previews, or long explanations unless /document is present.", "Do not start generation when no command/flow has been selected.", "Do not convert DSA/AppShell theme files through /convert /bricks.", "Do not use prior Kiwe validation material, old National Chikki/BioVantage attempts, previous browser-AI outputs, local downloads, search results, or accepted notes unless the human supplied those exact files in the current turn or explicitly asked for comparison." ], "firstResponse": { "mustReport": "SeamFlow contract: 7.26", "ifListCommand": "Read command-manifest.json, return compact command list, then stop.", "ifOtherCommand": "Route only that command. Always fetch fresh discovery with a unique nonce first, verify contractVersion, releaseId and sourceHash, then read only the selected immutable command route and its hash-declared pinned resources.", "ifFilesNoCommand": "Inspect supplied file contents, classify current artifact stage, and offer deterministic raw /convert /bricks or one-pass /convert /bricks /seamframework for raw HTML/CSS/JS. Explain that accessibility is independent: bare /accessibility works on the current raw /ideate page, and /create /accessibility plus /audit work on raw, Bricks, or Framework artifacts. Show Route A hosted SEAM Compiler, Route B local deterministic compiler, Route C Plugin REST authority bridge, and Route D Plugin REST + Companion review. Ask for credentials only for Route C/D or live plugin proof.", "ifNoFilesNoCommand": "Return compact /list summary and ask what the human wants to create, rebuild, audit, fix, convert, or apply." }, "freshness": { "discoveryTemplate": "https://start.kiwelaunch.com/.well-known/kiwe.json?refresh={UTC_TIMESTAMP_OR_RANDOM_NONCE}", "canonicalCache": "no-store", "immutableCache": "public, max-age=31536000, immutable", "integrity": "Require one shared releaseId/sourceHash and verify each pinned resource sha256 before execution.", "fallback": "GitHub raw is fallback-only; append a new refresh nonce and verify this contract version." }, "rawFiles": { "markdownEntrypoint": "https://start.kiwelaunch.com/start.md", "machineEntrypoint": "https://start.kiwelaunch.com/entry.json", "commandManifest": "https://start.kiwelaunch.com/command-manifest.json", "compilerContract": "https://raw.githubusercontent.com/Museintel/kiwe/main/kiwe-ai-toolkit/contracts/seam-compiler-contract.json", "workflow": "https://raw.githubusercontent.com/Museintel/kiwe/main/kiwe-ai-toolkit/contexts/workflow-lite.md", "ideation": "https://raw.githubusercontent.com/Museintel/kiwe/main/kiwe-ai-toolkit/contexts/ideate-lite.md" }, "pluginApi": { "rule": "When KIWE_REST_BASE and KIWE_AI_KEY are supplied, prefer plugin-hosted SeamFlow REST routes before manual generation or reconstructed validators.", "auth": "Use Authorization: Bearer {KIWE_AI_KEY} or X-Kiwe-AI-Key: {KIWE_AI_KEY}. Key scope must include seamflow, studio_ai, bricks_ai, or all.", "askWhenMissing": "If the human selected /usecompanion, Route C, Route D, plugin validation, or live Site Graph/API proof and credentials are missing, ask for KIWE_REST_BASE and KIWE_AI_KEY. Tell the human to create the key at WordPress Admin → Kiwe → AI → API access keys with seamflow, studio_ai, bricks_ai, or all.", "routes": { "status": "{KIWE_REST_BASE}/ai/seamflow/status", "classify": "{KIWE_REST_BASE}/ai/seamflow/classify", "rebuild": "{KIWE_REST_BASE}/ai/seamflow/rebuild", "audit": "{KIWE_REST_BASE}/ai/seamflow/audit", "frameworkProfile": "{KIWE_REST_BASE}/ai/seamflow/framework-profile", "convertBricks": "{KIWE_REST_BASE}/ai/seamflow/convert-bricks", "accessibility": "{KIWE_REST_BASE}/ai/seamflow/accessibility", "execute": "{KIWE_REST_BASE}/ai/seamflow/execute" }, "passAuthority": "Plugin route proof is PASS authority because it executes inside Kiwe against the current WordPress/Bricks environment." }, "navigationTree": { "freshDiscovery": "https://start.kiwelaunch.com/.well-known/kiwe.json?refresh={UTC_TIMESTAMP_OR_RANDOM_NONCE}", "start": "https://start.kiwelaunch.com/start.md", "entry": "https://start.kiwelaunch.com/entry.json", "commandManifest": "https://start.kiwelaunch.com/command-manifest.json", "contexts": { "workflow": "https://start.kiwelaunch.com/contexts/workflow-lite.md", "ideation": "https://start.kiwelaunch.com/contexts/ideate-lite.md", "seamAttributes": "https://start.kiwelaunch.com/contexts/seam-attributes-lite.md", "bricksConversion": "https://start.kiwelaunch.com/contexts/bricks-conversion-lite.md", "seamCompiler": "https://start.kiwelaunch.com/contexts/seam-compiler-lite.md", "accessibility": "https://start.kiwelaunch.com/contexts/accessibility-lite.md", "dynamic": "https://start.kiwelaunch.com/contexts/dynamic-lite.md", "combined": "https://start.kiwelaunch.com/contexts/combined-lite.md", "audit": "https://start.kiwelaunch.com/contexts/audit-lite.md" }, "tools": { "bricksConversionValidator": "https://raw.githubusercontent.com/Museintel/kiwe/main/kiwe-ai-toolkit/tools/validate-bricks-conversion.cjs", "accessibilityValidator": "https://raw.githubusercontent.com/Museintel/kiwe/main/kiwe-ai-toolkit/tools/validate-accessibility.cjs", "seamFrameworkValidator": "https://raw.githubusercontent.com/Museintel/kiwe/main/kiwe-ai-toolkit/tools/validate-seamframework.cjs", "seamFrameworkCompiler": "https://raw.githubusercontent.com/Museintel/kiwe/main/kiwe-ai-toolkit/tools/compile-seamframework.cjs", "frameworkProfileValidator": "https://raw.githubusercontent.com/Museintel/kiwe/main/kiwe-ai-toolkit/tools/validate-framework-profile.cjs", "auditOutput": "https://raw.githubusercontent.com/Museintel/kiwe/main/kiwe-ai-toolkit/tools/audit-output.cjs" } }, "compilerAuthority": { "contract": "kiwe-ai-toolkit/contracts/seam-compiler-contract.json", "rawConvert": "For /convert /bricks, run SEAM Compiler 0.13.0 or a compatible deterministic endpoint. Raw conversion is Framework-neutral and may produce arbitrary page, header, footer, and section templates.", "seamFramework": "For /convert /bricks /seamframework, use the preferred one-pass compiler mode so full raw evidence feeds one project-wide profile and its dependent templates. /seamframework remains valid while the raw conversion evidence is retained. AI-authored production JSON is forbidden.", "legacyRebuild": "/rebuild /seamframework is a compatibility alias normalized to raw Convert followed by optional Framework; legacy regex substitution is not production authority." }, "validatorAuthority": { "rule": "Only executed validator proof may close a lane as PASS. Valid proof is an official Kiwe validator command that actually ran, a Kiwe MCP validator result, a Kiwe REST/plugin validator result, or a hosted/local Kiwe validator endpoint result.", "browserAiFallback": "If the hosted compiler is down, use the official local compiler/runtime from this repository, then the Kiwe REST bridge. Browser AI may invoke and explain those tools but may not author production Bricks JSON, converted-project Framework Profiles, measured accessibility ratios, or PASS proof itself. If no official executable route is available, return WARN/UNVERIFIED.", "seamFrameworkStandalone": "validate-seamframework.cjs auto-detects Framework packages and runs the package validator for exact profile/template class IDs, variable definitions, single-owner styling, and compiler audit proof. Raw website/page artifacts retain the self-contained fallback when the fuller toolkit is unavailable.", "routeFallbackLadder": "Apply to every phase. Prefer Route D when /usecompanion and Plugin REST are reachable. If Companion fails, continue as Route C. If Plugin REST fails or DNS/HTTP cannot reach the host, and shell/Node/Git tools are available, immediately fall back to Route B and run the official matching validator/compiler. Only return WARN or UNVERIFIED after Plugin REST failed and no official Git/Node/MCP/hosted validator can execute.", "ifUnavailable": "Report WARN or UNVERIFIED for that lane. Do not write PASS, no blocking findings, or completed closure for Seam Framework, Framework profile, Bricks conversion, DSA theme, combined handoff, or accessibility when the relevant validator/tool/API did not execute.", "notPassAuthority": ["manual audit", "visual confidence", "copied validator logic", "reconstructed validator logic", "simulated validator logic", "equivalent checks", "prior accepted notes"], "proofShape": ["validator command/tool/route", "contract/version", "exit code or ok status", "fail count", "warning count", "artifact path/hash when available"], "mustUseWhenPossible": [ "validate-seamframework.cjs for /audit /seamframework; it auto-detects Framework packages and remains fallback-capable for raw page artifacts", "validate-framework-profile.cjs for /audit /frameworkprofile", "validate-bricks-conversion.cjs for /audit /bricksconversion", "validate-accessibility.cjs for /audit /accessibility", "audit-output.cjs for whole-output sanity" ] }, "errorHandling": { "rule": "SeamFlow is a command central. If the command, artifact, validator, route, token budget, context window, or requested lane is not valid enough to continue, stop immediately with a compact error instead of improvising.", "responseShape": [ "STATUS: NEEDS_INPUT | FAIL | WARN", "SeamFlow contract: 7.26", "ERROR: KIWE_...", "Command:", "Current artifact:", "Why stopped:", "Next valid command:" ], "codes": { "KIWE_UNKNOWN_COMMAND": "Unknown or misspelled command token; stop and suggest /list or nearest valid command.", "KIWE_MISSING_ARTIFACT": "Required current files/attachments are missing; stop and ask for them.", "KIWE_WRONG_LANE": "Supplied artifact does not qualify for the requested command; stop and suggest the matching command.", "KIWE_STALE_SOURCE_BLOCKED": "Only stale/prior outputs are available; stop and request current files.", "KIWE_VALIDATOR_UNAVAILABLE": "Official validator/tool/API cannot execute; report WARN/UNVERIFIED, not PASS.", "KIWE_VALIDATOR_PROOF_MISSING": "A command claimed PASS without executable validator proof; downgrade to FAIL/WARN and rerun the validator.", "KIWE_MANUAL_PASS_BLOCKED": "Command needs deterministic audit but only manual confidence is available; stop or report WARN.", "KIWE_PREVIOUS_AUDIT_MISSING": "/fix /previousaudit was requested without immediately previous audit findings.", "KIWE_PREVIOUS_OUTPUT_MISSING": "/previousoutput was requested but immediate previous output files are not accessible.", "KIWE_PREVIOUS_COMMAND_MISSING": "/redo was requested but the immediate previous output-producing instruction or its approved input snapshot is not accessible.", "KIWE_CONTEXT_WINDOW_RISK": "Requested flow is too large for the current AI/session; suggest /execute /stepbystep /audit /eachstep.", "KIWE_TOKEN_BUDGET_RISK": "Command is likely to waste tokens; suggest a smaller command or /audit /allattached first.", "KIWE_TOOL_UNAVAILABLE": "MCP/API/browser/validator tool unavailable; use raw route if possible, otherwise stop.", "KIWE_STALE_CONTRACT": "A later command follows refinements/output but the exact current entry, manifest, or routed context could not be refreshed; stop instead of using memorized command rules.", "KIWE_CONTRACT_INTEGRITY_FAILED": "Fresh discovery, release ID, source hash, or pinned resource hash disagrees; stop instead of mixing releases.", "KIWE_SEARCH_DRIFT": "A search engine, arXiv, GitHub search, commit browsing, or prior-example lookup was used or attempted instead of exact raw URL/context routing.", "KIWE_SITEGRAPH_REQUIRED": "Command explicitly requires live Site Graph/API data that was not supplied.", "KIWE_COMPANION_FALLBACK": "/usecompanion requested but unavailable; continue only if the base command can run without it.", "KIWE_STALE_BRICKS_PAGE_CSS": "Live Bricks preview/builder proof is contaminated by existing page-level Bricks custom CSS or old matching selectors; test on a clean page or clear Bricks page settings custom CSS before blaming the template." } }, "mcpPreference": { "rule": "If Kiwe MCP/tools are available, use tools before reading prose.", "sequence": [ "kiwe_get_start", "kiwe_get_command_manifest", "kiwe_seamflow_plan", "kiwe_plan_flow", "kiwe_diagnose_command", "kiwe_route_command", "lane validator such as kiwe_validate_framework_profile, kiwe_validate_bricks_conversion, or kiwe_validate_accessibility" ], "fallback": "If MCP/tool access fails, continue with rawFiles.machineEntrypoint and rawFiles.commandManifest.", "askToConnectOnlyWhen": "Ask once only when the human wants live Site Graph/API access, Companion review, or direct validator/tool execution and no Kiwe tool is available.", "companionHandshake": "If /usecompanion is selected and no MCP/tool is connected, ask for KIWE_REST_BASE and KIWE_AI_KEY. First call a bounded Companion status/context route. On success report COMPANION: connected with compact route/hash proof. On failure report COMPANION: fallback and continue without blocking." }, "flowPlanner": { "cli": "kiwe seamflow [--command text] [--artifact-summary text] [--desired-outcome text] [--use-companion]", "mcp": "kiwe_seamflow_plan", "compatibilityCli": "kiwe plan-flow", "compatibilityMcp": "kiwe_plan_flow", "purpose": "Classify artifacts and return the smallest safe SeamFlow command path through Seam, Framework profile, Bricks conversion, DSA theme, combined handoff, and accessibility." }, "classifier": { "rule": "Classify by actual file content/code first, not by attachment name. If uncertain, ask permission to audit before fixing or continuing.", "rawHtmlCssJs": ".html with audit -> fix actual artifact if needed -> same audit again until PASS or NEEDS_INPUT before moving on.", "/audit /atend": "Generation/conversion phases may proceed first, but final delivery still requires every relevant closing audit to pass.", "/audit /fix /atend": "Final delivery runs every required closure audit, fixes failed lanes, and reruns the same audits until PASS or NEEDS_INPUT." }, "byStartPoint": { "raw-html-css-js": ["/audit /bricksconversion"], "seam-page-artifact": ["/audit /bricksconversion"], "framework-profile": ["/audit /frameworkprofile"], "bricks-template-upload": ["/audit /bricksconversion", "/audit /accessibility"], "bricks-conversion-envelope": ["/audit /bricksconversion", "/audit /accessibility"], "dsa-theme-package": ["/audit /dsatheme", "/audit /accessibility"], "combined-handoff": ["/audit /combined", "/audit /accessibility"] }, "notAllowed": [ "Do not close from visual confidence alone.", "Do not skip /fix after a failed audit.", "Do not use stale audit reports from previous attempts as closure proof." ] }, "reportRule": "/report is an interaction flag. In /execute /stepbystep, return the current phase file and a compact report after the audit/fix loop closes, then wait for the human to say continue. In /execute /fullflow, it adds a compact final phase ledger but does not pause unless the human chose step-by-step.", "fullFlowStepRule": "Full-flow means one final delivery, not one giant context load. Internally run phase-by-phase, reading only the contexts/validators required by the current phase, then close that phase with /audit -> /fix -> /audit before continuing.", "fullFlowStopRule": "Stop at the first blocking audit failure that cannot be fixed from the supplied artifact; otherwise continue the /audit -> /fix -> /audit loop until required closure audits pass. Missing SiteGraph is not a blocker for static Bricks conversion or /usebrickscontext targets. /usesitegraph requires /for plus an explicit target and stops only when that selected target needs live site evidence or staging/apply authority.", "fullFlowDefaultFinalArtifacts": [ "framework/kiwe-framework-profile.json", "bricks-template/[page-name]-template-upload.json" ] }, "seamPurityRule": { "appliesTo": ["/seamframework", "/audit /seamframework", "/fix /seamframework"], "must": [ "Preserve design quality.", "Use official Seam semantic roles/classes/flows.", "Use Kiwe/Appsite capability attributes instead of duplicate runtime behavior.", "Use Kiwe/Seam variables or declared project variables for visual values.", "Declare reusable project variables/classes in framework profile settings.tokens.project so Kiwe > Framework can push them to Bricks project categories.", "Use Bricks-native element controls as the render/edit owner for full-page Bricks template uploads; use global variables for token definitions and keep imported global_classes semantic/name-only unless the command explicitly targets a class-library artifact.", "Use real fluid clamps only when source responsive states prove different min/max values." ], "fail": [ "no-op clamps such as clamp(22px, 22px, 22px)", "direct component colors such as #fff, rgba(...), hardcoded gradient stops, or --pack-bg: #... in Bricks element settings/custom CSS", "anonymous hardcoded lengths in token-owned Bricks settings", "CSS variable fallbacks in Bricks render-owner settings such as var(--nc-color-brand-dark, #85181c)", "duplicate visual ownership where element-native controls and styled imported global_classes both carry paint/layout/radius/spacing/typography", "live Bricks preview proof on a target page that still contains old pageSettings.customCss, #bricks-inline-css-page, or stale project selectors from previous imports" ], "allowed": [ "literal colors and fixed primitive values at token/global-variable definition layer", "bare CSS variable consumption in Bricks render-owner settings when paired Framework profile proof exists", "project-specific variables/classes when prefixed, collision-safe, and declared under settings.tokens.project rather than universal overrides" ], "livePreviewProof": "If a live Bricks preview/builder URL is used as evidence, inspect the target page for #bricks-inline-css-page, #bricks-frontend-inline-inline-css, #dynamic-element-css, bricks-inline-css-* style blocks, page settings customCss/_cssCustom buckets, and old matching .nc-*/.bv-*/promo-card/product-card/screen/bento selectors. If stale page CSS is present and not part of the current attached artifact, stop with KIWE_STALE_BRICKS_PAGE_CSS. A clean proof must say whether the test used a blank page, a page with cleared Bricks page settings, or a contaminated page." }, "accessibilityRule": { "appliesTo": [ "/accessibility", "/create /accessibility", "/audit /accessibility", "/fix /accessibility" ], "checks": [ "approved current artifact and light-mode art direction remain source authority", "bare /accessibility runs audit, minimal fix, render and re-audit rather than returning advice only", "WCAG contrast for text, pills, cards, controls, focus, and foreground/background pairs", "native light/dark proof through data-kiwe-theme and data-brx-theme", "responsive reflow at desktop, tablet, mobile and narrow widths", "card flex/grid growth, repeated-component sizing and CTA/footer alignment", "critical text clipping, wrapping, overlap, viewport overflow and touch-control collisions", "reduced motion where motion exists", "preservation of content, hierarchy, brand identity, distinctive composition, interaction intent, Seam classes, Kiwe attributes, Bricks dynamic tags, query-loop intent, and DSA/AppShell boundaries", "dark mode is a deliberate semantic peer expression with brand and hierarchy parity, not an inversion or generic near-black compliance palette", "technical accessibility proof remains separate from subjective visual-parity and human/device review" ], "fixPolicy": "Outside dark mode, use the least visually disruptive evidence-backed repair and existing tokens/classes first. Dark mode may use wider bounded visual judgment for semantic surfaces, elevation, borders, shadows, translucency, imagery treatment and accent distribution. Never influence /ideate or claim aesthetic preference is scientifically certified.", "closure": ["approvedDesignPreserved", "lightModeArtDirectionPreserved", "darkModeArtDirection", "darkModeParityReview", "responsiveUsabilityReviewed", "repeatedComponentsReviewed", "light/dark renderProof at desktop/tablet/mobile/narrow"] }, "defaultFinalResponse": [ "STATUS: PASS | FAIL | WARN | NEEDS_INPUT", "SeamFlow contract: 7.26", "Command:", "Artifact classification:", "Files returned:", "Blocking findings:", "Warnings:", "Next suggested command:" ] }