Adoption

Adoption is how an existing folder becomes a Nocturnal project.

Import and sync

Import a project (rail plus → Import) registers the folder. Nothing is written into the repo. The rail shows it as pending until you sync project info. Create a project is different — Nocturnal already writes .nocturnal/ and AGENTS.md, so there is nothing to adopt.

Sync project info (and later Update project info) walks the project and writes a .nocturnal/ config: how to run it, which ports it uses, scripts, links, and a one-time stack snapshot. If you leave the setting on, it also adds a short Nocturnal section to that repo's AGENTS.md so agents in that project know how to start and stop things.

Rescan is manual. Live updates keep ports, git, processes, and CI current after that.

Ports

Sync project info records the ports the project already uses. If they clash with another synced project, the dashboard offers a remap you review before sending. You can also move every declared service onto free ports on demand.

Keep the config current

When you add a script, process, or link in the repo, update the matching fields in .nocturnal/ in the same change. The dashboard picks that up. Rescan is for a stale stack snapshot, not for those operational fields.

The rule file

Download the adoption rule and run it from any agent if you want a new repo set up the same way.