# `.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": "Online Shop",
  "description": "Starter e-commerce storefront.",
  "agentId": "w4c-startup",         // default agent for project chats
  "tags": ["web", "e-commerce"],
  "source": { "template": "wiz4apps/templates.OnlineShop" }
}
```

## `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": "online-shop",
  "title": "Online Shop",
  "description": "…",
  "thumbnail": ".w4c/preview.svg",
  "agentId": "w4c-startup",
  "defaultName": "online-shop",     // default repository name in the dialog
  "skills": ["project-bootstrap"],  // marketplace skills installed + attached on create
  "fields": [
    { "key": "storeName", "label": "Store name", "type": "text", "required": true }
  ],
  "promptTemplate": "…",
  "elements": [
    { "kind": "diagram", "name": "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.