A Velk project is one folder. Knowing what lives where tells you what the AI is changing when you ask for something, and which parts nobody should touch. The short version: structure is a file, content is the database, the look is PHP.
What's in the folder
| Folder or file | What it holds |
|---|---|
theme/ | Your site: site.json (the structure), templates/ (the HTML of each kind of page, in PHP), partials/ (pieces reused across pages, such as the header and footer), functions.php (the theme's own code, such as a webhook or the wording of messages) and the CSS. |
core/ | The engine. Replaced whole on every update. |
bin/, config/, index.php | Also the engine: the bin/velk command tool, the code that reads .env, and the front door every visit goes through. |
storage/ | Uploaded media, files sent through forms, cache and logs. |
.env | Passwords and keys of this copy: database, email, payments. Your computer and the server each have their own. |
migrations/ | The database changes each version brings. They run once and are removed, so don't be surprised when the folder is gone. |
.htaccess, robots.txt | The project's copies of the engine's examples. Yours to adjust; updates leave them alone. |
.velk-version | Which engine version is installed. |
.deploy/ | Created when you first publish or connect a site: how to reach the server. It stays on your computer. |
AGENTS.md, README.md, CHANGELOG.md, docs/ | The engine's documentation, including the reference AI agents read. |
Structure, content and look
- Structure is a file.
theme/site.jsondeclares what the site can hold: which pages, which content types, which fields each one has. The admin panel is generated from it, so changing the file changes the panel. - Content is the database. Texts, posts, registered images, form submissions and users live in MySQL. That's what the client edits, and it's why copying
theme/to another project takes the structure and the look, but none of the content. - The look is PHP. Templates are PHP files with HTML, plus the theme's CSS. No template language, no visual builder.
The golden rule: never edit the engine
The engine is everything Velk ships: core/, config/, bin/, migrations/, index.php, the .example files and the engine's documents. An update replaces those paths whole. An edit there vanishes on the next update without a warning, and until then your copy quietly differs from the one on the server.
Everything a site needs goes in theme/. When the engine lacks something, that's a request for Velk, not a local patch. The skill follows this rule, and before a first deploy it compares the engine with the official release and refuses to publish an edited one.
Ask the AI
Explain the folders of this project in plain words: what each one holds, what I change by asking you, and what nobody should edit.
A good first request in a project you didn't build, or one you're coming back to.
Ask the AI
Check whether the engine of this project matches the official Velk release, file by file.
The AI runs the skill's engine check. It answers that the engine is intact, or lists each file that was changed, added or is missing.
What you change by asking
| You ask for | What changes |
|---|---|
| A field, page, content type or form | theme/site.json, then the template that shows it. The panel updates itself. |
| A different look | The theme's templates and CSS. |
| A post, a new text, a photo | No file at all: that's content, done in the panel, or by the AI on a live site. |
| A setting of this copy, such as the panel's language | .env. |
| A new Velk version | The engine paths, through the update flow. Never by hand. |
Optional: a history with Git
Git records the history of a project: each milestone you save keeps the whole state of the files, so you can see what changed between two days and go back when something breaks. It pays off in Velk because the structure is a text file: a field added last Tuesday shows up in the history and can be undone.
The engine is installed from a release, not from Git, and the install removes the engine's own .gitignore (the list of what Git skips). The project's list is yours to write, and it's where secrets and uploads are kept out of the history.
Ask the AI
Start versioning this project with Git. Leave out .env, the .deploy folder and storage, and save a first milestone called “site structure”.
From then on, one sentence saves each milestone: “Save a milestone: added the contact form.”