Site code reference

Project files

Which folders and files in a Starjay site you can read and write, which are managed by a tool, and what is refused.

All paths are relative to the site's root. An AI agent writes files with write_file and patch_file; both check every path against the rules on this page. A refused write changes nothing and returns a message saying where the change belongs instead.

What you can read

read_file and search_files can read anything under src/, content/ and brand/, plus site.json. Everything else is off limits to direct reads. Use the matching tool instead: list_forms for forms, list_components for the component list, browse_assets for images, redirects_list for redirects, seo_get_page for SEO.

What you can write

Path	What goes there
`src/pages/`	Pages. Astro file-based routing: `src/pages/about.astro` is `/about`, `src/pages/blog/[slug].astro` is `/blog/:slug`.
`src/components/sections/`	Full-width page blocks: Hero, Features, CTA.
`src/components/layout/`	Site-wide chrome reused across pages: Navbar, Footer, Container.
`src/components/ui/`	Small reusable building blocks: Button, Card, Badge.
`src/lib/`	Helpers, data and types. No components.
`src/styles/`	Extra stylesheets. No components.
`src/head/` and `src/body/`	Exactly four snippet files. See Head and body snippets.
`src/marks.json`	Your text marks. See Pages and components.
`content/pages/**.json`	The wording of each page.
`content/components/**.json`	The default wording of each component.

Subfolders inside the three component folders are fine.

Files managed by a tool

Writing these directly is refused. Use the tool named instead.

Path	Use instead
`brand/tokens.ts`, `brand/theme.css`	`modify_tokens` for colors and fonts, `modify_element_defaults` for site-wide element styles. `brand/theme.css` is generated from `brand/tokens.ts`.
`brand/brand-guide.md`	`set_brand_guide`
`src/layouts/Base.astro`	`modify_layout` for the header and footer; the four snippet files for raw `<head>` and `<body>` content
`src/styles/globals.css`	Generated from your design tokens. Use `modify_tokens` or `modify_element_defaults`.
`src/live.config.ts`	Declares your CMS collections automatically. Use `modify_collection` and `modify_items`.
`site.json`	`modify_layout` (header, footer, page navigation and transitions) and `seo_set_defaults` (site SEO)
`content/seo/`	`seo_set_page`. A new page gets its SEO file automatically.
Other files under `content/`	The CMS tools. Collections aren't files.
`platform/forms/`	`modify_form`
`platform/redirects.json`	`redirects_modify`
`platform/assets.json`	`import_asset` and the other image tools
`platform/publish-state.json`	`set_publish_state`
`platform/components.json`	Nothing. It's rebuilt automatically when you create components.
`src/pages/robots.txt.ts`	`seo_set_page` and `seo_set_defaults`. The file is regenerated on every publish.

Refused outright

Path	Why
`.env` files and `node_modules`	Protected.
`public/`, `astro.config.mjs`, `package.json`, `tsconfig.json` and any other file outside `src/` and `content/`	Only site source is writable.
Anything in `src/layouts/` other than `Base.astro`	Alternative layouts aren't supported. A page that skips `Base` loses its SEO tags, snippets and theme.
`src/middleware.ts`	Published sites are static; redirects are managed with `redirects_modify`.
`src/content.config.ts`	Build-time content collections would create a second content system the CMS can't see.
`src/env.d.ts`	Not needed.
`src/fetch.ts` (and `.js`, `.mjs`, `.mts`)	Reserved by Astro's request pipeline. Use a name such as `src/lib/fetch-data.ts`.
`src/lib/seo.ts`	Platform SEO code.
Any other file or folder directly under `src/`	`src/` has a fixed structure.
`.astro`, `.tsx` or `.jsx` files in `src/lib/` or `src/styles/`	Components belong in the three component folders.
`.tsx` or `.jsx` files in `src/pages/`	Not pages. React components don't work at all; see What isn't supported.
A component outside `src/components/sections/`, `layout/` or `ui/`	Components must live in one of the three folders.
A page path with a segment starting with `_`	The underscore address space is reserved, and Astro never serves those files anyway.
Any other file in `src/head/` or `src/body/`	Those folders hold exactly the four snippet files.
RSS feed files (`content/rss/`, `src/pages/feeds/`, `rss.xml.ts`)	RSS feeds aren't available.

Deleting files

Deleting is a little more permissive than writing, so you can clean up stray files anywhere under src/ (for example a leftover file in src/layouts/ or a misplaced component). You still can't delete managed files or the four snippet files. To empty a snippet file, write it with an empty body.

What happens automatically after a write

New page: its SEO file is created, and the page starts Ready, so it goes live on the next publish.
New component: it's added to the component list.
Every page or component write: Starjay renders the file. If the render fails, the write still happens but the result reports success: false with the render error, so you can fix it.
When the change ends: visible text in the .astro files you touched moves into content/pages/ and content/components/. See Pages and components.