From af2a2ae9f3c0d3a7b904fedd71e61a37fa3a81aa Mon Sep 17 00:00:00 2001
From: SemianiakaVY <admin@wiz4chat.com>
Date: Thu, 17 Sep 2026 21:07:43 +0000
Subject: [PATCH] chore(template): sync .w4c/README.md

---
 .w4c/README.md | 116 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 116 insertions(+)
 create mode 100644 .w4c/README.md

diff --git a/.w4c/README.md b/.w4c/README.md
new file mode 100644
index 0000000..7c9e8b6
--- /dev/null
+++ b/.w4c/README.md
@@ -0,0 +1,116 @@
+# `.w4c/` — project folder contract
+
+Everything W4C needs to treat a repository as a **project** lives here. The
+folder is committed with the repository, so project metadata and seed assets
+travel with the code.
+
+```
+.w4c/
+├── project.json                     # project metadata (source of truth in-repo)
+├── template.json                    # present only in template repositories
+├── preview.svg                      # catalog thumbnail for templates
+├── diagrams/
+│   └── architecture.excalidraw.json # Excalidraw scenes
+├── boards/
+│   └── roadmap.json                 # board columns + seed tasks
+└── workflows/
+    └── ci-build.yaml                # workflow definitions (same YAML shape as the workflows module)
+```
+
+## `project.json`
+
+Marks the repository as a project and carries its metadata. A repository
+without this file (or without a server-side project record) is just a
+repository — selecting it optionally creates a project from it.
+
+```jsonc
+{
+  "schema": 1,
+  "name": "Website & Resource Research",
+  "description": "Audit an existing website and plan a redesign.",
+  "agentId": "w4c-startup",         // default agent for project chats
+  "tags": ["web", "research"],
+  "source": { "template": "wiz4apps/templates.WebsiteResearch" }
+}
+```
+
+## `template.json` (templates only)
+
+Catalog descriptor for the template picker on the start page: the dialog
+fields the user fills in, the prompt assembled at start, and the list of
+elements to import.
+
+```jsonc
+{
+  "schema": 1,
+  "id": "website-research",
+  "title": "Website & Resource Research",
+  "description": "…",
+  "thumbnail": ".w4c/preview.svg",
+  "agentId": "w4c-startup",
+  "defaultName": "website-research", // default repository name in the dialog
+  "skills": ["project-bootstrap"],   // marketplace skills installed + attached on create
+  "fields": [
+    { "key": "siteUrl", "label": "Main page URL", "type": "text", "required": true }
+  ],
+  "promptTemplate": "…",
+  "elements": [
+    { "kind": "diagram", "name": "Site map & architecture", "path": ".w4c/diagrams/architecture.excalidraw.json" }
+  ]
+}
+```
+
+`fields[].type` is one of `text | textarea | number | select | boolean`.
+`select` fields also declare `options`; other fields may declare `default`
+and `placeholder`. `promptTemplate` supports `{{key}}` interpolation plus the
+service tokens `{{title}}`, `{{repoFullName}}` and `{{elements}}`.
+
+If `elements` is omitted, the importer may discover assets by folder
+convention (`diagrams/`, `boards/`, `workflows/`).
+
+## Elements
+
+| Kind | Folder | Format |
+|------|--------|--------|
+| `diagram` | `diagrams/` | Excalidraw scene JSON (`{"type":"excalidraw", ...}`) |
+| `board` | `boards/` | `{ name, columns[], tasks[] }` |
+| `workflow` | `workflows/` | Workflow YAML (see `w4c-workflows-api` `WorkflowDefinition`) |
+| `widget` | `widgets/` | Widget definition JSON (reserved) |
+
+## `boards/roadmap.json` — the build stages
+
+The board seed is the canonical **layer → task** list for the project. The
+Startup Creator (`w4c-startup`) reads it on the first turn and materialises one
+board card (repository issue) per entry in the project's own repository, then
+hands the user over to My Boards. A card is only "done" when its acceptance
+criterion has been shown at runtime.
+
+```jsonc
+{
+  "schema": 1,
+  "name": "Project roadmap",
+  "columns": [                                  // the board's real grouping
+    { "id": "high", "name": "High Priority" },
+    { "id": "low", "name": "Low Priority" },
+    { "id": "none", "name": "No Priority" },
+    { "id": "done", "name": "Done" }
+  ],
+  "tasks": [
+    {
+      "icon": "🗺️",                            // unicode icon, prefixed to the card title
+      "title": "Architecture diagram — architecture, ERD and key flows",
+      "column": "high",                         // target column id
+      "labels": ["High Priority"],
+      "body": "…goal, deliverables, acceptance criteria, references…"
+    }
+  ]
+}
+```
+
+Keep the layer set complete: plan, design mockups, architecture diagram,
+database & forms, backend/API, frontend code, admin, control panel, workflows,
+deploy and quality. Agent provisioning is deliberately **not** a bootstrap
+stage — creating a specialist agent is a follow-up the user starts on purpose.
+
+Element import from a repository is not active yet; the descriptors above are
+the stable contract for when it is.