Hosting with 20% off when you buy through the link

Project structure

What lives in each folder of a Velk project, the rule that keeps updates safe (never edit the engine) and how to keep a history with Git.

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 fileWhat 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.phpAlso 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.
.envPasswords 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.txtThe project's copies of the engine's examples. Yours to adjust; updates leave them alone.
.velk-versionWhich 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.json declares 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 the AI runs
# the skill's script: compares the engine paths with the published release $ scripts/check-engine.sh --project . ✓ ENGINE_OK

What you change by asking

You ask forWhat changes
A field, page, content type or formtheme/site.json, then the template that shows it. The panel updates itself.
A different lookThe theme's templates and CSS.
A post, a new text, a photoNo 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 versionThe 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.”

What the AI runs
# start versioning this folder $ git init # mark everything that changed and save the milestone $ git add -A $ git commit -m 'site structure' # see the history $ git log --oneline