# VLCode-Lite — Project Instructions

## Test Project Convention

All test/demo VL projects used for workflow testing or feature verification live under:

```
~/Documents/VLProjects/_tests/
├── AdjustTest/          ← adjustment workflow test project
│   ├── Config/
│   │   └── ProjectConfig
│   ├── Apps/
│   ├── Sections/
│   ├── Services/
│   ├── Database/
│   ├── Theme/
│   └── .vl-code/
│       └── ProjectMeta.json
├── CompileTest/         ← compile workflow test
└── ...
```

### Rules:
- **Root**: `~/Documents/VLProjects/_tests/` — test-only projects, not production
- **Naming**: PascalCase, suffix with `Test` for clarity
- **Cleanup**: Test projects can be deleted freely; they carry no production data
- **Never mix**: Do NOT put test projects inside VLCode-Lite source tree

## Workspace Management (WorkspaceManager Tool)

AI Assistant can create, switch, and list workspaces via the `WorkspaceManager` tool. The left-side file tree syncs automatically after any create/switch operation.

| Action | Parameters | Description |
|--------|-----------|-------------|
| create | projectName, parentDir?, autoSwitch? | Scaffold new VL project, add to workspace list, auto-switch |
| switch | dirPath | Switch active workspace, file tree + tabs update |
| list | (none) | List all registered workspaces |

### Creation Rules:
- **projectName**: PascalCase, English-only (e.g. `MyApp`, not `my-app` or `我的应用`)
- **parentDir defaults**: `~/Documents/VLProjects` for production, `~/Documents/VLProjects/_tests` for test projects
- **autoSwitch**: defaults to `true` — after creation, workspace switches and file tree updates immediately
- **Standard structure** created automatically: `Apps/`, `Sections/`, `ExtComponents/`, `Services/`, `Database/`, `Theme/`, `Config/`, `.vl-code/`
- **Existing directory**: if target already exists and is non-empty, tool warns instead of overwriting

### Usage Examples:
```
# Create test project (AI tool call)
WorkspaceManager({ action: "create", projectName: "AdjustTest", parentDir: "~/Documents/VLProjects/_tests" })

# Switch to existing project
WorkspaceManager({ action: "switch", dirPath: "/Users/ivx/Documents/VLProjects/SmartCampus" })

# List all workspaces
WorkspaceManager({ action: "list" })
```

## Adjustment Workflow System

VLCode-Lite provides multiple adjustment workflows via the `VLAdjust` tool:

| Workflow | JSON File | Use Case |
|----------|-----------|----------|
| add-page | add-page.json | Add a new page/section/route |
| add-service | add-service.json | Add a new backend service domain |
| theme-customize | theme-customize.json | Modify theme tokens |
| general | incremental-update.json | General modifications (meta diff → regen) |
| add-feature | feature-adjust.json | Add feature to existing page (button, form, chart) |
| modify-data | data-adjust.json | Add/modify database fields with cascade |
| batch | batch-adjust.json | Multiple small adjustments in one pass |

## Development

- Port: 3300 (dev server)
- Entry: `bin/vlcode-lite.js`
- Tools: `src/tools/` (factory pattern, registered in `src/tools/index.js`)
- Workflows: `.vl-code/workflows/` (runtime JSON currently `3.16`; canonical spec doc is DocCenter Path `3`, `VL Workflow Spec 3.18`)