# Beginner Steps. Advanced AI.
**PUBLISHED GUIDE**
Build your first website with an AI agent.
Instructions last reviewed: 2026-10-08. Recheck software instructions, links and prices before using them.
Follow the steps in order. The checkboxes are personal reminders; they do not certify that a site is tested, secure or ready to publish.
## Contents
- [1. Set up Codex](#agentic-harness) (Set up)
- [2. Create your GitHub project](#github-account) (Set up)
- [3. Open the project on your computer](#local-project) (Set up)
- [4. Choose your OpenAI access](#openai-access) (Set up)
- [5. Keep private information safe](#secrets) (Set up)
- [6. Give Codex your working rules](#working-agreements) (Set up)
- [7. Add four useful skills](#design-quality-skills) (Set up)
- [8. Write your website brief](#website-brief) (Plan)
- [9. Plan your pages and content](#sitemap-content) (Plan)
- [10. Choose a simple website setup](#technical-foundation) (Plan)
- [11. Choose your website’s look](#visual-direction) (Plan)
- [12. Plan small build stages](#implementation-plan) (Plan)
- [13. Build your first page](#build-the-foundation) (Build & check)
- [14. Finish the other pages](#complete-the-pages) (Build & check)
- [15. Try the website as a visitor](#test-as-a-visitor) (Build & check)
- [16. Review security and privacy](#review-security-and-privacy) (Build & check)
- [17. Make the site faster and clearer](#polish-speed-and-search) (Build & check)
- [18. Review the site and set up automatic checks](#review-and-automate-checks) (Publish & maintain)
- [19. Publish your site and check it online](#publish-and-verify) (Publish & maintain)
- [20. Keep your site working](#maintain-and-improve) (Publish & maintain)
## 1. Set up Codex
Phase: Set up
Install the desktop app, choose a practice folder, and try your first Codex task.
An ordinary chat suggests code. An agent can inspect files, edit them, run commands, check results, and make corrections. The harness supplies these tools and controls access. You decide what to build and whether it is ready.
Our example is Fieldnotes Studio, a fictional business with Home, About, Services, and Contact pages. The current official quickstart installs the ChatGPT desktop app, then selects Codex inside it. Follow the linked instructions if labels change.
### Do this
1. Use the [official desktop quickstart](https://learn.chatgpt.com/docs/quickstart) to install the ChatGPT desktop app for your computer.
**Install the app**
Illustrated example: Illustration: download the ChatGPT desktop app, install it, then open it. Kooka points to the open app.
- **Click path:** Download → Install → Open
**Look for:** The desktop app opens on your computer.
2. Open the app and [sign in with ChatGPT](https://learn.chatgpt.com/docs/auth). Use the account you want to work with.
**Sign in**
Illustrated example: Illustration: choose Sign in, finish signing in with your account in a browser, and return to the desktop app.
- **Click path:** Sign in → Finish in browser → Return to app
**Look for:** The account you intended to use is signed in.
3. Make an empty website-workshop folder inside Documents: [Mac instructions](https://support.apple.com/guide/mac-help/organize-files-with-folders-mh26885/mac) or [Windows instructions](https://support.microsoft.com/en-us/word/create-a-new-folder).
**Make your practice folder**
Illustrated example: Illustration: open Documents, create a new folder named website-workshop, then open it and check that it is empty.
- **Mac:** Finder → Documents → File → New Folder
- **Windows:** File Explorer → Documents → New → Folder
- **Both:** Name it website-workshop. Press Return or Enter, then double-click it.
**Look for:** An empty website-workshop folder inside Documents.
A folder holds files, like a labelled drawer. Documents is already on your computer. Make website-workshop inside it as a practice space; leave it empty for now. Click the instructions for your computer. Menu names use English; Documents may appear as Documenten in Dutch.
**On a Mac — show the clicks**
1. Click Finder, the blue smiling-face icon in the Dock. The Dock is the row of app icons, usually at the bottom of your screen. [Apple&\#39;s Finder introduction](https://support.apple.com/en-euro/guide/mac-pro/apddf030866a/mac) shows what it looks like.
2. Click Documents on the left of the Finder window. If it is missing, use the menu bar at the very top of the screen: click [Go, then Documents](https://support.apple.com/guide/mac-help/go-directly-to-a-specific-folder-on-mac-mchlp1236/mac).
3. With Documents open, click File in that top menu bar, then New Folder. Type website-workshop, all lowercase with a hyphen, and press Return on your keyboard.
4. Double-click website-workshop to open it. Check that its name is at the top of the window and that there are no files or other folders inside. Leave this window open so you can find it again.
**On Windows — show the clicks**
1. Open File Explorer, the folder-shaped icon on the taskbar at the bottom of your screen. If you cannot find it, hold the Windows-logo key, tap E, then release both keys. [Microsoft&\#39;s File Explorer guide](https://support.microsoft.com/en-us/windows/experience/fileexplorer/file-explorer-in-windows) explains this window.
2. Click Documents on the left of File Explorer. You can also click Home and open Documents under Quick access. If it is missing, click Home, then the Up arrow beside the address bar, and open Documents from the folders shown.
3. With Documents open, click New in the toolbar at the top of the window, then Folder. If your version has a New folder button, use that. Type website-workshop, all lowercase with a hyphen, and press Enter on your keyboard.
4. Double-click website-workshop to open it. Check that the address bar at the top ends in Documents > website-workshop and that there are no files or other folders inside. Leave this window open so you can find it again.
**You should now see:** An empty folder named website-workshop inside Documents. The location is Documents → website-workshop; the arrow means ‘inside’. If Documents also shows iCloud or OneDrive, it may be synced, but you still select the folder through your computer&\#39;s file window. If website-workshop already exists and contains files, create website-workshop-practice instead and use that name throughout this chapter.
4. Select Codex from the ChatGPT menu. [Add a local project](https://learn.chatgpt.com/docs/projects?surface=app) using Documents → website-workshop, then start a New chat.
**Connect your folder**
Illustrated example: Illustration: in Codex choose Add project, select Documents and website-workshop, confirm the folder, and start a New chat.
- **Click path:** ChatGPT menu → Codex → Add project → Documents → website-workshop
- **Then:** Open on Mac / Select Folder on Windows → New chat. Choose Local if asked.
**Look for:** Your new chat belongs to website-workshop.
Return to the desktop application you installed in action 1. Connecting a local project tells Codex which folder contains your work. You are selecting the folder you just made; you do not need to upload it or create another copy.
**Open your practice folder in Codex**
1. If the application shows ChatGPT, click the ChatGPT dropdown near the top left and select Codex, as shown in the [official desktop quickstart](https://learn.chatgpt.com/docs/quickstart). If you are already in Codex, continue.
2. In Codex&\#39;s left sidebar, choose Add project. If you see a Projects page first, open it and use its option to add a project. Choose a local folder on this computer if the application asks where the project should live.
3. A folder-selection window opens. Click Documents on its left, then select website-workshop. Confirm with Open on Mac or Select Folder on Windows; the button wording can vary. Select website-workshop itself, rather than the whole Documents folder.
4. Check that website-workshop appears as a project in Codex&\#39;s sidebar. Click that project, then start a New chat within it. If the chat offers a Work in choice, choose Local, meaning this computer.
**You should now see:** A new Codex chat associated with the folder name you chose: website-workshop, or website-workshop-practice if you used the alternative name. It is fine that the project has no website files yet. In chapter 3, you will open a different folder containing your GitHub project; keep this practice folder for now.
5. Choose [Ask for approval](https://learn.chatgpt.com/docs/permission-modes) below the message box. It allows project edits and asks before extra access.
**Choose your permissions**
Illustrated example: Illustration: open the permissions control below the message box and select Ask for approval. A shield marks the project workspace and a question marks requests for extra access.
- **Click path:** Below the message box → Permissions → Ask for approval
**Look for:** Ask for approval is selected. Read extra-access requests before approving them.
Permissions decide what Codex can do and when it asks you first. A workspace means the project folder selected in action 4. Ask for approval lets Codex edit files in that workspace and do routine local work; it asks before actions that need extra access. It does not ask before every change inside the folder.
**Find the setting and understand a request**
1. Look just below the message box where you will type your request. Open the permissions control: it may display the current mode, such as Ask for approval, Approve for me, or Full access.
2. Select Ask for approval. If it already displays that mode, leave it selected. You do not need to enable extra modes in Settings for this exercise.
3. If an approval request appears during a later task, read what access or command it requests and why. For example, ‘install the website&\#39;s packages’ means downloading supporting software for the project. Approve the specific request once when it matches the task you gave.
4. If a request names a different project, asks to delete files, or is unclear, choose its deny or cancel option. Ask Codex: ‘Explain what this request would do and why it is needed, in plain language.’ Keep Ask for approval selected while you learn.
**You should now see:** Ask for approval shown below the message box. In action 6, your first message explicitly asks Codex to inspect the folder without changing it. That is an instruction for this task; the selected permission mode still permits changes inside the workspace.
6. Copy and send the [read-only orientation prompt](#agentic-harness-prompts). Check that Codex names your folder and leaves it empty.
**Try your first task**
Illustrated example: Illustration: copy the orientation prompt, paste it into Codex and send it. Check that the response names website-workshop and that no files changed.
- **Click path:** Copy prompt → Paste into Codex → Send
**Look for:** Codex identifies your folder without changing its files.
Basics, explained
**Documents and a project folder**
Documents is a standard folder on your computer. A project folder is a folder you choose for one piece of work, such as website-workshop inside Documents. Keep all files for that project together there.
**Local and cloud**
Local means the agent works with files on your computer. Cloud means work runs on a remote computer. This exercise uses a local folder. A folder inside Documents may also be backed up by iCloud or OneDrive.
**Folder-selection window**
A window that lets you browse your computer and choose a folder for an application. Select the intended project folder and confirm with the window&\#39;s Open or Select Folder button.
**Agentic harness**
The software environment around an AI model that supplies tools, project context, working instructions, and permission controls.
**AI agent**
An AI system that can work through a task using tools and feedback, such as editing a page and checking it in a browser.
**Workspace**
The folder or environment containing the project files the agent is working on.
**Permission**
A rule determining which files, commands, network connections, or apps the agent can access.
### Prompt: Your first Codex task
```text
I am new to building websites with an AI agent. Inspect this folder without changing files or installing anything. Name the folder, explain your tools and permissions, and describe how I will review changes. Explain unfamiliar words.
```
### Check your work
- [ ] The application opens and the account shown is the one you intended to use.
- [ ] Codex identifies your chosen practice folder (website-workshop or website-workshop-practice), and Ask for approval is selected.
- [ ] The orientation task finishes without creating or changing project files.
If something goes wrong
**I added a project, but Codex is using the wrong folder.**
Open that project&\#39;s menu and choose Edit project. Check its attached folder. Use Add folder to attach Documents → website-workshop, remove any folder you did not intend to attach, and make website-workshop primary if several folders are listed. Start a new chat in that project.
**Codex cannot read the folder.**
Confirm the selected folder and inspect the permission request. Grant access to that project folder or use an ordinary Documents folder.
### Official links & further reading
- [Official desktop installation and quickstart](https://learn.chatgpt.com/docs/quickstart)
- [Official Codex authentication options](https://learn.chatgpt.com/docs/auth)
## 2. Create your GitHub project
Phase: Set up
Create a free GitHub account and a private home for your website files.
GitHub stores project files and their saved history. GitHub Free is enough for this private practice project.
Private limits access to the source. It does not make a published website private or keep passwords safe.
### Do this
1. Create a [GitHub Free account](https://docs.github.com/en/account-and-profile/how-tos/account-management/creating-an-account-on-github). Choose a username and verify your email.
**Create your account**
Illustrated example: Illustration: create a free GitHub account and verify its email address.
- **Click path:** GitHub → Sign up → Verify email
**Look for:** Your GitHub account opens and your email is verified.
GitHub is separate from OpenAI. GitHub Free supports private repositories, so no paid subscription is needed here. Advanced features and hosting services have their own plans. A repository stores project files and history. Private visibility limits source access; it does not secure the website or stop hosting from publishing it later. Never store credentials in repositories.
**Show the steps**
1. Follow the [GitHub account creation guide](https://docs.github.com/en/account-and-profile/how-tos/account-management/creating-an-account-on-github), choose a username, finish registration, and verify your email.
2. Use an email address you can access. Choose the Free personal plan if GitHub offers a choice.
3. Open the verification email and follow its instructions; check spam if it does not arrive.
**You should now see:** Your GitHub account opens and your email is verified.
2. In GitHub, open Settings → Password and authentication. Set up [two-factor authentication](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication) with an authenticator app.
**Protect your sign-in**
Illustrated example: Illustration: link an authenticator app through GitHub&\#39;s two-factor authentication settings.
- **Click path:** Profile picture → Settings → Password and authentication → Enable two-factor authentication
**Look for:** Your authenticator app is linked; finish by saving recovery codes in the next action.
Follow these steps if you want more help.
**Show the steps**
1. Open your profile picture > Settings > Password and authentication. [Enable two-factor authentication](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication) using an authenticator app and complete verification.
2. Use an authenticator app you trust on your phone or computer.
3. Follow GitHub&\#39;s scan or setup-key instructions inside your own account, then enter the app&\#39;s temporary code.
4. Keep the setup secret and codes private. Continue to the recovery-code screen; the next action completes setup.
**You should now see:** Your authenticator app is linked; finish by saving recovery codes in the next action.
3. Save your [recovery codes](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication-recovery-methods) in a password manager. Confirm you can find them, then finish setup.
**Save your backup codes**
Illustrated example: Illustration: keep recovery codes in protected storage and confirm they are saved.
- **Click path:** Save recovery codes → Password manager → Confirm saved
**Look for:** Two-factor authentication is enabled and you can find your recovery codes.
Follow these steps if you want more help.
**Show the steps**
1. Save your [GitHub recovery codes](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication-recovery-methods) in a password manager or another protected location independent of your phone. Confirm you can find them.
2. On the Save your recovery codes screen, download or copy the codes into protected storage.
3. Check that you can open the saved item independently of your authenticator device. Avoid leaving an unprotected copy in Downloads.
4. Back on GitHub, choose I have saved my recovery codes to finish enabling two-factor authentication.
**You should now see:** Two-factor authentication is enabled and you can find your recovery codes.
4. Choose GitHub’s plus menu → [New repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/quickstart-for-repositories). Name it fieldnotes-studio, choose Private, and turn Add README on.
**Prepare your repository**
Illustrated example: Illustration: name the repository fieldnotes-studio, choose Private, and enable Add README.
- **Click path:** Plus menu → New repository
- **Choose:** fieldnotes-studio → Private → Add README: On
**Look for:** The form shows fieldnotes-studio, Private, and Add README turned on.
Follow these steps if you want more help.
**Show the steps**
1. Use GitHub&\#39;s plus menu > New repository, following the [repository creation instructions](https://docs.github.com/en/repositories/creating-and-managing-repositories/quickstart-for-repositories). Name it fieldnotes-studio, choose Private, and enable Add README.
2. Choose your own account as the repository owner.
3. Use the exact name fieldnotes-studio so later commands match. Review the form before creating it.
**You should now see:** The form shows fieldnotes-studio, Private, and Add README turned on.
5. Click [Create repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/quickstart-for-repositories). Bookmark its page; chapter 3 uses your-username/fieldnotes-studio.
**Create and bookmark it**
Illustrated example: Illustration: create the private repository and bookmark its GitHub page.
- **Click path:** Create repository → Bookmark the page
**Look for:** The repository page shows fieldnotes-studio, Private, and README.md.
Follow these steps if you want more help.
**Show the steps**
1. Create and bookmark the repository. The address ends in your-username/fieldnotes-studio; use that exact name when [connecting the local project in chapter 3](#local-project).
2. Check the Private label and README.md on the new repository page.
3. your-username is a placeholder for your real GitHub username. Note that owner/project part of the address.
4. Creating a repository stores source files; it does not publish a website.
**You should now see:** The repository page shows fieldnotes-studio, Private, and README.md.
6. Open README.md → Edit. Add a short project description, then [commit your first change](https://docs.github.com/en/repositories/creating-and-managing-repositories/quickstart-for-repositories) and find it in the history.
**Save your first change**
Illustrated example: Illustration: edit and preview README.md, then save a named commit.
- **Click path:** README.md → Pencil / Edit → Preview → Commit changes
- **Message:** Describe practice website
**Look for:** GitHub history contains your README change and its commit message.
Follow these steps if you want more help.
**Show the steps**
1. Follow GitHub&\#39;s [first-commit walkthrough](https://docs.github.com/en/repositories/creating-and-managing-repositories/quickstart-for-repositories): open README.md, choose Edit, and add a project description. Commit with the message Describe practice website, then find the history entry.
2. Use a description such as: A four-page practice website for Fieldnotes Studio.
3. Choose Preview and review the text before selecting Commit changes.
4. For this new private practice project, save the small README edit to the current default branch. Chapter 3 creates a separate build branch.
**You should now see:** GitHub history contains your README change and its commit message.
Basics, explained
**Repository**
A project folder together with a history of changes. GitHub stores repositories online; your computer will hold a local copy.
**Commit**
A named snapshot of selected project changes, with a message explaining what changed.
**Two-factor authentication**
A second sign-in check beyond your password, such as a temporary code from an authenticator app.
**README**
The introductory file explaining what a project is and how someone can work with it.
### Prompt: Make sense of GitHub
```text
Explain a repository, a commit, and a local copy using a four-page website. I created a private repository called fieldnotes-studio with a README. Explain what I should see. Do not request credentials or recovery codes.
```
### Check your work
- [ ] Your GitHub email is verified and two-factor authentication is enabled.
- [ ] You can find your saved recovery codes without placing them in the project.
- [ ] The fieldnotes-studio repository shows the Private label and your README commit.
If something goes wrong
**GitHub asks you to buy a plan.**
Choose the Free personal plan. This private practice repository does not require Pro.
**You cannot create the repository.**
Check email verification, including spam. Follow GitHub&\#39;s verification help before creating another account.
### Official links & further reading
- [Create a GitHub account](https://docs.github.com/en/account-and-profile/how-tos/account-management/creating-an-account-on-github)
- [Compare GitHub plans](https://docs.github.com/en/get-started/learning-about-github/githubs-plans)
- [Configure two-factor authentication](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication)
- [Create a repository and first commit](https://docs.github.com/en/repositories/creating-and-managing-repositories/quickstart-for-repositories)
## 3. Open the project on your computer
Phase: Set up
Install three tools, download your GitHub project, and open it in Codex.
Git saves versions. Node runs website-building tools, and npm installs their packages. GitHub CLI, called gh, helps this walkthrough connect to GitHub.
A branch keeps your build work separate. Run commands one at a time and read each result before continuing.
### Do this
1. Install [Git](https://git-scm.com/install/), [Node LTS](https://nodejs.org/en/download), and [GitHub CLI](https://cli.github.com/) for your computer. Reopen the terminal afterward.
**Install the three tools**
Illustrated example: Illustration: install Git, Node LTS with npm, and GitHub CLI from official sources.
- **Install:** Git → Node LTS → GitHub CLI
**Look for:** All three tools are installed on your computer.
Git records versions; GitHub stores them online. Node runs development tools, and npm installs their packages. Use current Node LTS supported by Astro: this draft requires at least 22.12 and excludes odd-numbered releases. This walkthrough uses GitHub CLI, gh, for browser login and cloning. Codex CLI is optional when using the desktop app. Run commands separately; resolve errors before continuing.
**Show the steps**
1. Install [Git](https://git-scm.com/install/), [Node LTS](https://nodejs.org/en/download), and [GitHub CLI](https://cli.github.com/) using the official instructions for your operating system. Reopen the terminal afterward.
2. Use the official installation instructions for your operating system. npm comes with Node.
3. [Astro requires Node 22.12 or higher](https://docs.astro.build/en/install-and-setup/) and does not support odd-numbered Node versions.
4. GitHub CLI&\#39;s command name is gh. It is different from Codex CLI, which is optional when using the desktop app.
**You should now see:** All three tools are installed on your computer.
2. Open Terminal on Mac or PowerShell on Windows. Run the [version checks](#local-project-example-1) one line at a time.
**Check the tools**
Illustrated example: Illustration: check installed tools in Terminal or PowerShell and read their version results.
- **Mac:** Terminal → Version checks
- **Windows:** PowerShell → Version checks
**Look for:** Git, Node, npm and gh return version numbers; Node meets Astro’s requirement.
Follow these steps if you want more help.
**Show the steps**
1. Open Terminal on macOS/Linux or PowerShell on Windows. Run the [installed-tool version checks](#local-project-example-1) one command at a time; each should return a version number.
2. On Mac, find Terminal with Spotlight. On Windows, open Start and search for PowerShell.
3. Copy one line from Check installed tools, paste it into the terminal, press Enter, and inspect the result.
4. If a command is missing, reopen the terminal and inspect that tool&\#39;s installation before continuing.
**You should now see:** Git, Node, npm and gh return version numbers; Node meets Astro’s requirement.
3. Run [gh auth login](https://cli.github.com/manual/gh_auth_login). Choose GitHub.com → HTTPS → Browser, finish signing in, then run gh auth status.
**Connect the terminal to GitHub**
Illustrated example: Illustration: sign GitHub CLI in through a browser and check its authentication status.
- **Choose:** GitHub.com → HTTPS → Browser sign-in
- **Then:** gh auth status
**Look for:** gh auth status identifies your intended GitHub account without showing a token.
Follow these steps if you want more help.
**Show the steps**
1. Run [gh auth login](https://cli.github.com/manual/gh_auth_login). Choose GitHub.com, HTTPS, browser authentication, and Yes if asked to authenticate Git. Complete the browser flow, then run gh auth status.
2. This signs GitHub CLI into GitHub; it does not change your Codex or OpenAI account.
3. If prompted to authenticate Git, choose Yes. Finish the browser flow in your own account.
4. Never share any temporary device code or token. Check the account shown by gh auth status.
**You should now see:** gh auth status identifies your intended GitHub account without showing a token.
4. Open Documents: [Mac](#local-project-example-2) / [Windows](#local-project-example-3). Run the [clone commands](#local-project-example-4), replacing YOUR\_USERNAME with your GitHub username.
**Download your project**
Illustrated example: Illustration: clone fieldnotes-studio from GitHub and open its local copy.
- **Start in:** Terminal or PowerShell → Documents
- **Run:** gh repo clone YOUR\_USERNAME/fieldnotes-studio
- **Then:** cd fieldnotes-studio
**Look for:** Your computer has fieldnotes-studio with README.md and the project’s Git history.
Download your GitHub repository into Documents using the [clone commands](#local-project-example-4); [GitHub CLI explains cloning](https://cli.github.com/manual/gh_repo_clone).
**Start in Documents**
1. On Mac, open Terminal and copy [Open Documents on a Mac](#local-project-example-2). Paste it and press Return.
2. On Windows, open PowerShell and copy [Open Documents on Windows](#local-project-example-3). Paste it and press Enter. This asks Windows for your [Documents folder](https://learn.microsoft.com/en-us/dotnet/api/system.environment.getfolderpath), including a redirected location.
3. Then copy the [clone commands](#local-project-example-4). Replace YOUR\_USERNAME with your GitHub username, and run each line in order.
4. If fieldnotes-studio already exists there, stop and ask Codex to inspect it. Do not delete or overwrite an existing project.
**You should now see:** Your computer has fieldnotes-studio with README.md and the project’s Git history.
5. Inside fieldnotes-studio, run the [author and branch commands](#local-project-example-5). Replace the example name and email; check git status shows codex/first-site.
**Create your build branch**
Illustrated example: Illustration: set a project commit author and create the codex/first-site branch.
- **Set:** Your commit name and email
- **Run:** git switch -c codex/first-site → git status
**Look for:** Git knows your commit author and reports the codex/first-site branch.
Follow these steps if you want more help.
**Show the steps**
1. Inside fieldnotes-studio, use the [project author commands](#local-project-example-5). Replace the example values; for privacy, copy your [GitHub noreply commit email](https://docs.github.com/en/account-and-profile/how-tos/email-preferences/setting-your-commit-email-address) from Settings > Emails.
2. The two git config commands apply to this project. Replace their example name and email before running them.
3. Run git switch -c codex/first-site, then git status. If the branch already exists, ask Codex to inspect it before creating another.
4. The next action connects Codex to this repository instead of the practice folder.
**You should now see:** Git knows your commit author and reports the codex/first-site branch.
6. [Open fieldnotes-studio in Codex](https://learn.chatgpt.com/docs/projects?surface=app). In its new chat, send the [connection-check prompt](#local-project-prompts) before changing files.
**Check the project in Codex**
Illustrated example: Illustration: inspect fieldnotes-studio in Codex and verify its README and branch without editing.
- **Click path:** Codex → Local project → fieldnotes-studio → New chat
- **Then:** Copy connection prompt → Send
**Look for:** Codex confirms the repository, remote, branch and tool versions without editing files.
Follow these steps if you want more help.
**Show the steps**
1. Run the [branch creation commands](#local-project-snippets) to create codex/first-site and check git status. [Open fieldnotes-studio as the Codex local project](https://learn.chatgpt.com/docs/projects), replacing website-workshop.
2. Ask Codex to explain saving and recovering changes. Inspect edits with [git diff](https://git-scm.com/docs/git-diff); [restoring a file](https://git-scm.com/docs/git-restore) discards uncommitted edits, so review them first.
3. Choose the downloaded fieldnotes-studio folder itself, not Documents or website-workshop. Select Local if asked.
4. Send Confirm the connection. Compare its response with README.md, the GitHub repository and codex/first-site.
5. Restoring a file can discard uncommitted edits. Review what would be lost before using recovery commands.
**You should now see:** Codex confirms the repository, remote, branch and tool versions without editing files.
Basics, explained
**Terminal**
A window for typing computer commands. Enter runs a command; cd followed by a folder path moves into that folder. Read each result before continuing.
**Clone**
Download a working copy of a repository, including its recorded history.
**Branch**
A named line of changes that lets you develop work separately before combining it with the main version.
**LTS**
Long Term Support: a release line maintained for stability and fixes over a longer period.
### Prompt: Confirm the connection
```text
Inspect without editing. Confirm the repository, GitHub remote, branch, and tool versions. Explain git diff, committing, pushing to GitHub, and safely recovering one file. Never discard changes without showing what would be lost.
```
### Check installed tools
```shell
git --version
node --version
npm --version
gh --version
```
### Open Documents on a Mac
```sh
cd "$HOME/Documents"
```
### Open Documents on Windows
```powershell
Set-Location ([Environment]::GetFolderPath("MyDocuments"))
```
### Clone your repository
```shell
gh repo clone YOUR_USERNAME/fieldnotes-studio
cd fieldnotes-studio
```
### Set project author and create a branch
```shell
git config user.name "Your Name"
git config user.email "YOUR_GITHUB_EMAIL"
git switch -c codex/first-site
git status
```
### Check your work
- [ ] Version checks return numbers, and Node meets Astro requirements.
- [ ] gh auth status identifies the intended account without showing a token.
- [ ] Codex sees README.md in fieldnotes-studio; git status reports codex/first-site.
If something goes wrong
**A command is not recognised.**
Reopen the terminal. Follow the tool&\#39;s PATH instructions: PATH lists locations your computer searches for commands.
**Cloning fails.**
Check username and repository spelling. Confirm gh auth status matches an account that can open the private repository.
### Official links & further reading
- [Install Git](https://git-scm.com/install/)
- [Download Node LTS](https://nodejs.org/en/download)
- [Install GitHub CLI](https://cli.github.com/)
- [Git: restoring individual files](https://git-scm.com/docs/git-restore)
## 4. Choose your OpenAI access
Phase: Set up
Keep using ChatGPT sign-in, or explore the optional API route and its separate costs.
ChatGPT sign-in uses your plan’s access. API keys use separately billed OpenAI Platform usage; a paid ChatGPT plan does not pay your API bill.
This static website needs no OpenAI key. Steps 3–5 are optional; skip them if you keep ChatGPT sign-in.
### Do this
1. Open Codex’s profile menu. Check your account and [sign-in method](https://learn.chatgpt.com/docs/auth); keep ChatGPT sign-in if it already works.
**Check your account**
Illustrated example: Illustration: confirm your Codex account and ChatGPT sign-in method.
- **Click path:** Codex → Profile menu → Account / sign-in status
**Look for:** You know which account and sign-in route Codex is using.
ChatGPT subscription access and OpenAI API billing are separate. A ChatGPT subscription does not include API-key credit. Local Codex supports either route; API usage charges your Platform account. Codex cloud requires ChatGPT sign-in, and some features differ. The finished static website needs no OpenAI key. AI helps build it; visitors receive ordinary pages. A future chatbot would need its own protected backend and operating budget.
**Show the steps**
1. Check Codex&\#39;s profile menu for the intended account and [authentication route](https://learn.chatgpt.com/docs/auth). Continue with ChatGPT sign-in if tasks already work.
2. Confirm the intended personal or work account is active.
3. If ChatGPT tasks already work, keep that route. Skip optional actions 3–5 and continue to action 6.
4. Local Codex supports both methods; cloud requires ChatGPT sign-in, and available features can differ.
**You should now see:** You know which account and sign-in route Codex is using.
2. Read [how billing works](https://learn.chatgpt.com/docs/auth). ChatGPT sign-in and API-key usage have separate bills; choose which route you want.
**Understand the two bills**
Illustrated example: Illustration: ChatGPT plan access and optional API usage have separate billing.
- **Choose:** ChatGPT sign-in: plan access / API key: separate usage bill
**Look for:** You know which account pays for your chosen route.
Follow these steps if you want more help.
**Show the steps**
1. Read [how authentication affects billing](https://learn.chatgpt.com/docs/auth), then inspect your account&\#39;s current usage controls. Set your own spending preference before longer tasks and check current plan details in your account.
2. Do not buy API credits simply because you are building a static website.
3. API authentication uses standard Platform API rates rather than included ChatGPT plan credits.
4. A future visitor-facing chatbot would need a protected backend and its own running budget.
**You should now see:** You know which account pays for your chosen route.
3. Optional API route: open [OpenAI Platform Billing](https://platform.openai.com/settings/organization/billing/overview). Review its terms before adding payment or credits.
**Optional: set up API billing**
Illustrated example: Illustration: review the optional Platform API billing route before accepting charges.
- **Optional click path:** OpenAI Platform → Billing → Review account costs
**Look for:** If you choose API sign-in, Platform billing is ready and you understand its costs.
Follow these steps if you want more help.
**Show the steps**
1. Optional API route: sign in to [OpenAI Platform Billing](https://platform.openai.com/settings/organization/billing/overview) and add payment or credits as required by your account.
2. Skip this action if staying with ChatGPT sign-in.
3. Review the requirements displayed for the Platform account you intend to bill.
4. Only add payment or credits if you accept those charges. Keep payment details out of chat and project files.
**You should now see:** If you choose API sign-in, Platform billing is ready and you understand its costs.
4. Optional API route: create a practice-project key in [API keys](https://platform.openai.com/api-keys). Add an expiry date and save it privately.
**Optional: create a private key**
Illustrated example: Illustration: create an expiring optional API key and save it privately.
- **Optional click path:** Practice project → API keys → Create key → Password manager
**Look for:** Any API key is stored privately and belongs to your intended Platform project.
Follow these steps if you want more help.
**Show the steps**
1. Create or select a practice project in the Platform dashboard. In its [API keys area](https://platform.openai.com/api-keys), create a named secret key with an expiry date and save it to a password manager.
2. Create or select a practice project in the Platform account you intend to bill.
3. Save the secret directly in your password manager while the dashboard makes it available.
4. Never put it in fieldnotes-studio, screenshots or Codex chat. It authenticates Codex; the static pages do not need it.
**You should now see:** Any API key is stored privately and belongs to your intended Platform project.
5. Optional API route: set a [hard spend limit](https://developers.openai.com/api/docs/guides/spend-limits), then [sign in using the key](https://learn.chatgpt.com/docs/auth). Add an alert for earlier warnings.
**Optional: cap spending and sign in**
Illustrated example: Illustration: set an optional API hard limit before using the private key in the app&\#39;s sign-in field.
- **Set first:** Project settings → Limits → Spend → Edit spend limit → Enforce a hard limit → Save
- **Then:** Signed-out app → Sign in another way → Key field → Continue
**Look for:** API sign-in works with a saved project hard limit and early-warning alerts.
Follow these steps if you want more help.
**Show the steps**
1. Follow the [project hard-spend-limit instructions](https://developers.openai.com/api/docs/guides/spend-limits): Project settings > Limits > Spend > Edit spend limit. Set your monthly amount, enable Enforce a hard limit, and save.
2. For API authentication, use the [official desktop API-key sign-in instructions](https://learn.chatgpt.com/docs/auth). Sign out if needed, choose Sign in another way, enter the key in that authentication field, and continue.
3. Skip this action for ChatGPT sign-in. Set cost controls before running API tasks.
4. Alerts warn but do not stop requests. A hard cap stops affected traffic once tracked spend reaches it; enforcement can lag slightly.
5. On the app&\#39;s signed-out screen, paste the key only into the authentication field, never into the chat message box.
6. Add spend alerts below your accepted limit for earlier warnings.
**You should now see:** API sign-in works with a saved project hard limit and early-warning alerts.
6. In Codex, send the [billing-check prompt](#openai-access-prompts). Try a small task, then inspect usage for your chosen account.
**Check access and usage**
Illustrated example: Illustration: try a small Codex task and find usage for the chosen account.
- **In Codex:** Copy billing prompt → Send → Small task
- **Then:** Your chosen account → Usage information
**Look for:** A small task works and you can find the usage information for the account paying for it.
Follow these steps if you want more help.
**Show the steps**
1. Add [spend alerts for earlier warnings](https://developers.openai.com/api/docs/guides/spend-limits), then run a small task and inspect usage. Alerts do not stop requests; hard limits do, but enforcement can lag slightly.
2. Send Check the billing boundary in your project chat. It explains both routes without requesting your key.
3. Try a tiny read-only task, such as asking Codex to identify README.md.
4. Inspect your plan&\#39;s relevant usage information for ChatGPT sign-in, or Platform usage for API sign-in. Check the actual account dashboard yourself.
**You should now see:** A small task works and you can find the usage information for the account paying for it.
Basics, explained
**API**
An interface that lets one program request services from another, such as asking an OpenAI model for a response.
**API key**
A secret credential that authorises software requests and may allow charges to your account.
**Usage-based billing**
Charges based on the resources a service consumes, rather than one fixed subscription fee.
**Authentication**
The process of proving which account or credential is requesting access.
### Prompt: Check the billing boundary
```text
Explain ChatGPT sign-in versus API-key billing for Codex. I am building a static website with no visitor AI feature. Explain the required access, where to inspect usage, and what cost controls to verify. Never request my key.
```
### Check your work
- [ ] You know your authentication route and which account pays for its usage.
- [ ] A small task works, and you can find its relevant usage information.
- [ ] Any API key is stored privately, outside chat and project files.
If something goes wrong
**API requests fail despite a paid ChatGPT plan.**
Inspect Platform billing and project access separately. ChatGPT subscription access does not fund API requests.
**API authentication lacks a feature.**
Check the official authentication guide. Use ChatGPT sign-in if the feature requires that account or workspace.
### Official links & further reading
- [Official authentication and API billing distinction](https://learn.chatgpt.com/docs/auth)
- [OpenAI Platform API key dashboard](https://platform.openai.com/api-keys)
- [OpenAI Platform billing dashboard](https://platform.openai.com/settings/organization/billing/overview)
- [Configure API spend alerts and hard limits](https://developers.openai.com/api/docs/guides/spend-limits)
## 5. Keep private information safe
Phase: Set up
Protect passwords and keys, and check what will enter your project history.
Visitors can inspect browser code. Passwords and keys belong in protected storage, never in the code sent to their browser.
Git keeps old versions. If a key leaks, revoke it first; deleting today’s file does not make that key safe.
### Do this
1. Keep keys and recovery codes in a [password manager or secure storage](https://developers.openai.com/api/docs/guides/production-best-practices), outside chat and fieldnotes-studio.
**Keep secrets outside the project**
Illustrated example: Illustration: keep credentials in private storage rather than a website folder or chat.
- **Store:** Passwords, keys and recovery codes → Protected storage
**Look for:** Private credentials stay outside chat and the website project.
Git remembers old commits: deleting a key from today&\#39;s file leaves its history. Revoke exposed credentials at their provider before addressing repository history. Private repositories are not secret managers. Environment variables supply settings to tools. A .env file can hold local settings, but is unnecessary for desktop sign-in. Visitors can read browser code; Astro PUBLIC\_ variables must contain public information only.
**Show the steps**
1. Use a password manager for recovery codes and keys, following [credential protection guidance](https://developers.openai.com/api/docs/guides/production-best-practices). Use application sign-in flows rather than creating credentials documents in fieldnotes-studio.
2. Use the app&\#39;s sign-in flow instead of creating a passwords document in your project.
3. A private GitHub repository is not a secret manager. Keep secrets out of screenshots, logs, prompts and source files.
4. This static website needs no OpenAI key.
**You should now see:** Private credentials stay outside chat and the website project.
2. Send the [secret-boundary prompt](#secrets-prompts). Ask Codex to merge the [.gitignore starter rules](#secrets-example-1) without deleting existing entries.
**Ignore local private files**
Illustrated example: Illustration: merge .gitignore rules to exclude local settings and generated files from new commits.
- **In Codex:** Copy secret-boundary prompt → Send
- **Review:** .gitignore → Existing entries preserved
**Look for:** The merged .gitignore excludes local secret files and generated folders.
Follow these steps if you want more help.
**Show the steps**
1. Ask Codex to merge the [starter .gitignore rules](#secrets-example-1) with existing entries. Consult [GitHub ignored-files guidance](https://docs.github.com/en/get-started/git-basics/ignoring-files) and preserve current exclusions.
2. Open the merged .gitignore and compare it with the starter rules.
3. The rules exclude node\_modules, dist, .astro, .env and .env.\* while allowing a harmless .env.example.
4. An ignore rule affects untracked files; it does not remove files already committed or erase their history.
**You should now see:** The merged .gitignore excludes local secret files and generated folders.
3. This static site [needs no .env file](https://docs.astro.build/en/guides/environment-variables/). If you document future settings, put only harmless examples in .env.example.
**Use harmless examples**
Illustrated example: Illustration: this static site needs no .env; optional examples contain harmless settings only.
- **For this site:** No .env needed
- **If useful later:** .env.example → Harmless settings only
**Look for:** The project contains no unnecessary credential file or real secrets in examples.
Follow these steps if you want more help.
**Show the steps**
1. This static site needs no .env file. If documenting future settings, use .env.example with harmless values; review [Astro environment variables](https://docs.astro.build/en/guides/environment-variables/) so no real secret is included.
2. Do not create a .env file just because a tutorial mentions one.
3. An optional .env.example is documentation. Use clearly harmless placeholder settings rather than copying real secrets.
4. Astro PUBLIC\_ settings can reach the visitor&\#39;s browser and must contain public information only.
**You should now see:** The project contains no unnecessary credential file or real secrets in examples.
4. For a future backend, [check where settings run](https://docs.astro.build/en/guides/environment-variables/). Ask Codex which values visitors can read before adding any secret.
**Keep future keys on the server**
Illustrated example: Illustration: private keys stay on the server, while browser code and PUBLIC\_ settings are public.
- **Optional future feature:** Ask where each setting runs → Server or browser?
**Look for:** You understand why browser code and PUBLIC\_ values cannot hide a key.
Follow these steps if you want more help.
**Show the steps**
1. For a future backend service, use [local environment settings](https://docs.astro.build/en/guides/environment-variables/) and hosting secret controls. Ask Codex where each value runs and whether visitors can read it.
2. This plans a future feature; it does not add a backend now. A working email link needs no secret.
3. For any later service, ask which code runs on a server and which code goes to the browser.
4. Use protected hosting secret settings for server credentials. A disguised string or hidden form field in browser code is still readable.
**You should now see:** You understand why browser code and PUBLIC\_ values cannot hide a key.
5. Run the [ignore and change checks](#secrets-example-2). Ask Codex to flag suspected secrets by filename and type, without printing their values.
**Review before committing**
Illustrated example: Illustration: check ignored files and review changes without printing suspected secret values.
- **Run:** git check-ignore .env → git status → git diff
- **In Codex:** Report filenames and secret types only
**Look for:** The ignore check returns .env and pending changes contain no credentials or recovery codes.
Follow these steps if you want more help.
**Show the steps**
1. Before committing, review git status and [git diff](https://git-scm.com/docs/git-diff). Ask Codex to identify suspected secrets without printing their values.
2. Run git check-ignore .env inside fieldnotes-studio; it should return .env even without creating that file.
3. Inspect git status and git diff. Stage and review newly added files too; ordinary git diff does not display untracked file contents.
4. Ask for suspected secret locations and types only. Resolve them before committing; this review is evidence, not a guarantee of security.
**You should now see:** The ignore check returns .env and pending changes contain no credentials or recovery codes.
6. If a key leaks, [revoke it with its provider](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository). Deleting the file does not remove the key from history.
**Know what to do after a leak**
Illustrated example: Illustration: revoke a leaked credential before addressing files and saved history.
- **If a key leaks:** Provider settings → Revoke key → Review exposure and history
**Look for:** You know to revoke an exposed credential before cleaning up files and history.
Follow these steps if you want more help.
**Show the steps**
1. If a credential reaches chat, Git, screenshots, or a public page, revoke it immediately. Follow [sensitive-data recovery guidance](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository); deleting the exposure is insufficient.
2. This is recovery guidance, not a request to revoke a working key. Skip it if nothing has leaked.
3. Revoke exposed credentials at their provider first. Replace them only if the service still needs them.
4. Then address repository history and other copies. .gitignore cannot erase old commits or untrack an existing file automatically.
**You should now see:** You know to revoke an exposed credential before cleaning up files and history.
Basics, explained
**Secret**
A value that grants access, such as a password, API key, private token, or recovery code.
**Environment variable**
A named setting supplied to a running program by its environment. It can hold public configuration or private credentials.
**.gitignore**
A file listing local paths Git should leave untracked. It does not remove files already committed.
**Backend**
Code running on a server or service, where private credentials and protected operations can stay away from the visitor&\#39;s browser.
### Prompt: Set up the secret boundary
```text
Review credential exposure without printing secrets. Merge sensible Astro and local-secret .gitignore rules, preserving existing entries. This static site needs no API keys. Report suspected credentials by filename and type only. Explain ignoring new files versus removing tracked files.
```
### Starter exclusions to merge into .gitignore
```text
node_modules/
dist/
.astro/
.env
.env.*
!.env.example
```
### Check that a local environment file would be ignored
```shell
git check-ignore .env
git status
git diff
```
### Check your work
- [ ] git check-ignore .env returns .env, even without creating that file.
- [ ] Pending changes contain no credentials or recovery codes.
- [ ] You understand why browser code and PUBLIC\_ values cannot hide keys.
If something goes wrong
**An ignored secret remains tracked.**
Ask Codex to inspect tracking and preserve the local file while removing tracking. Revoke exposed credentials first; history remains.
**Codex requests a key for ordinary pages.**
Explain that Codex is already authenticated. Ask which actual website service requires the key before adding one.
### Official links & further reading
- [OpenAI guidance on protecting API credentials](https://developers.openai.com/api/docs/guides/production-best-practices)
- [Astro environment variables and public values](https://docs.astro.build/en/guides/environment-variables/)
- [GitHub: ignore files](https://docs.github.com/en/get-started/git-basics/ignoring-files)
- [GitHub: remove sensitive data from a repository](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository)
## 6. Give Codex your working rules
Phase: Set up
Save a short instruction file so Codex knows how to work on your website.
AGENTS.md is a plain-text instruction file Codex reads when work starts. It records the project’s expectations and checks.
Instructions guide the agent; they do not create tests or replace permissions. You still review results and decide when to publish.
### Do this
1. Download [AGENTS.md](https://kookaburraadvies.nl/guides/advanced-agentic-website-design/files/AGENTS.md). Save it inside fieldnotes-studio, beside README.md.
**Save the starter rules**
Illustrated example: Illustration: save AGENTS.md next to README.md at the top level of fieldnotes-studio.
- **Save to:** fieldnotes-studio → AGENTS.md beside README.md
**Look for:** AGENTS.md appears beside README.md in the project folder.
Codex reads AGENTS.md when starting work. Use it to record project context, review expectations, and checks. Keep agreements readable and specific. AGENTS.md supplies standing expectations; skills supply focused workflows. Neither replaces permissions or proves correctness. You still inspect the results and decide when to publish.
**Show the steps**
1. Download the starter [AGENTS.md file](https://kookaburraadvies.nl/guides/advanced-agentic-website-design/files/AGENTS.md). Place it beside README.md in fieldnotes-studio, rather than inside docs.
2. The project root means the top-level fieldnotes-studio folder.
3. Keep this file out of website-workshop and out of a nested docs folder.
4. If your browser adds a suffix to a duplicate download, keep one clearly named AGENTS.md.
**You should now see:** AGENTS.md appears beside README.md in the project folder.
2. Open AGENTS.md as plain text. Check its [exact name and location](https://learn.chatgpt.com/docs/agent-configuration/agents-md); it must not end in .txt.
**Check the filename**
Illustrated example: Illustration: use the exact AGENTS.md filename and avoid an extra .txt extension.
- **Check:** AGENTS.md: capitals, .md, no extra .txt
**Look for:** The instruction file is plain text and named exactly AGENTS.md.
Follow these steps if you want more help.
**Show the steps**
1. Open the file as plain text. Check the [official AGENTS.md naming and placement rules](https://learn.chatgpt.com/docs/agent-configuration/agents-md): the filename must be AGENTS.md, with capital letters and no .txt extension.
2. Open it with a plain-text editor or Codex&\#39;s file viewer.
3. Confirm the full filename, including its extension. Some editors add .txt without making it obvious.
4. Other global or nested guidance may also apply; later ask Codex to list what it loaded.
**You should now see:** The instruction file is plain text and named exactly AGENTS.md.
3. Read the rules and adapt them to your [website brief](#website-brief): static Astro, npm, small changes, and protected secrets.
**Make the rules fit your site**
Illustrated example: Illustration: adapt AGENTS.md to your website brief and agreed way of working.
- **Read and adapt:** AGENTS.md → Your website requirements
**Look for:** The rules describe how you want Codex to work on this website.
Follow these steps if you want more help.
**Show the steps**
1. Read every agreement and adapt it to your [website brief](#website-brief): static Astro, npm, small changes, protected secrets, and understandable code.
2. The starter contains general agreements, not your business details. Add short context for Fieldnotes Studio and its four pages.
3. Keep rules you understand, and adjust wording that does not fit your project.
4. After chapter 8, compare this file with your full brief and update any mismatched decisions.
**You should now see:** The rules describe how you want Codex to work on this website.
4. Ask Codex to check [which project commands exist](https://docs.npmjs.com/cli/v11/using-npm/scripts/). Before setup, website tests and package.json may not exist yet.
**Use real check commands**
Illustrated example: Illustration: distinguish available package.json scripts from checks that still need to be created.
- **Ask Codex:** Find package.json → List existing scripts → Name missing checks
**Look for:** You can tell existing checks from ones that still need to be set up.
Follow these steps if you want more help.
**Show the steps**
1. Before scaffolding, website checks do not exist. After setup, use [scripts actually defined in package.json](https://docs.npmjs.com/cli/v11/using-npm/scripts/); an instruction to run tests does not create them.
2. It is normal for this new repository to have no package.json before the Astro setup chapter.
3. Ask Codex to inspect actual build, type-check and test scripts if the file exists.
4. Record missing checks as setup work. Never accept a claimed pass for a nonexistent command; update the rules after real scripts are created.
**You should now see:** You can tell existing checks from ones that still need to be set up.
5. Keep the [starter review and publication rules](https://kookaburraadvies.nl/guides/advanced-agentic-website-design/files/AGENTS.md): show a local preview, explain results, and ask before publishing or new spending.
**Keep review and spending rules**
Illustrated example: Illustration: review a local preview and require authorization before publishing or adding costs.
- **Rules:** Local preview → Your review → Publication authorization
**Look for:** Your agreements cover review, credentials, spending and publication.
Follow these steps if you want more help.
**Show the steps**
1. Retain the [Starter kit working agreements](https://kookaburraadvies.nl/guides/advanced-agentic-website-design/files/AGENTS.md) requiring a reviewable preview and your approval before deployment or new spending.
2. Keep the requirement to show a working preview, explain changed behaviour, and report validation evidence and limitations.
3. Publishing, sending real messages or changing production data requires authorization for that action.
4. Add your spending preference for new services. Adapt the wording to authorization already given; these rules do not replace permission controls.
**You should now see:** Your agreements cover review, credentials, spending and publication.
6. In a new Codex chat, send the [agreement-check prompt](#working-agreements-prompts). Review and save AGENTS.md using the [commit commands](#working-agreements-snippets).
**Confirm and save your rules**
Illustrated example: Illustration: confirm the working rules in a fresh chat, then stage, review and commit them.
- **In Codex:** New chat → Copy agreement prompt → Send
- **Save:** git add → Review staged diff → Commit AGENTS.md
**Look for:** Codex summarises the actual agreements and Git records the reviewed instruction file.
Follow these steps if you want more help.
**Show the steps**
1. Start a fresh project chat and use the [working-agreements confirmation prompt](#working-agreements-prompts). Compare its response with AGENTS.md, then stage, review, and commit using the [instruction-file commands](#working-agreements-snippets).
2. Compare the fresh chat&\#39;s response with the actual rules, including existing versus missing checks.
3. For a newly created file, run git add AGENTS.md before git diff --cached -- AGENTS.md; ordinary git diff does not show untracked content.
4. Read the staged diff before committing. Saving these rules is not a request to start building.
**You should now see:** Codex summarises the actual agreements and Git records the reviewed instruction file.
Basics, explained
**AGENTS.md**
A Markdown file containing persistent instructions and project context for the coding agent.
**Project root**
The top-level project folder; here it is fieldnotes-studio, containing README.md and the Git history.
**Markdown**
A plain-text format that uses simple markers for headings and lists. A .md file is readable without special software.
### Prompt: Confirm working agreements
```text
List the loaded instruction files and summarise AGENTS.md, including secrets, small changes, validation, spending, and deployment. Distinguish scripts that exist from checks still to establish. Do not start building yet.
```
### Stage, review, then save the instruction file
```shell
git add AGENTS.md
git diff --cached -- AGENTS.md
git commit -m "Add website working agreements"
```
### Check your work
- [ ] AGENTS.md appears beside README.md.
- [ ] A fresh project chat identifies and accurately summarises the agreements.
- [ ] Existing and future checks are distinguished, and Git records the reviewed instructions.
If something goes wrong
**Codex misses your new instructions.**
Check folder and filename, then start a fresh chat. Ask it to list loaded sources; global or nested instructions may apply.
**An instruction demands a nonexistent command.**
Use the actual package.json script or mark the check as something to establish during setup. Keep failures visible.
### Official links & further reading
- [Official AGENTS.md discovery and working instructions](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
- [GitHub: basic Markdown writing](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
## 7. Add four useful skills
Phase: Set up
Give Codex four clear workflows for design, readable code, testing and security.
A skill is a reusable workflow in a SKILL.md file. Project skills live inside .agents/skills so Codex can discover them.
These four workflows guide design, clean code, testing and security review. They cannot certify that a website is secure or free of bugs.
### Do this
1. Download and read the four skills: [design](https://kookaburraadvies.nl/guides/advanced-agentic-website-design/files/website-design-SKILL.md), [clean code](https://kookaburraadvies.nl/guides/advanced-agentic-website-design/files/clean-code-SKILL.md), [testing](https://kookaburraadvies.nl/guides/advanced-agentic-website-design/files/website-testing-SKILL.md), and [security](https://kookaburraadvies.nl/guides/advanced-agentic-website-design/files/website-security-SKILL.md).
**Download the four skills**
Illustrated example: Illustration: download and read the four starter skills for design, code, testing and security.
- **Download:** website-design · clean-code · website-testing · website-security
**Look for:** You have read all four starter files before using them.
A skill folder contains SKILL.md with a name, description, and instructions. Codex discovers project skills under .agents/skills and reads full guidance when using them. website-design covers visual direction; clean-code covers understandable implementation; website-testing checks visitor journeys; website-security reviews security boundaries. These workshop instructions cannot certify a site as secure or defect-free.
**Show the steps**
1. Download the four starter skills: [website-design](https://kookaburraadvies.nl/guides/advanced-agentic-website-design/files/website-design-SKILL.md), [clean-code](https://kookaburraadvies.nl/guides/advanced-agentic-website-design/files/clean-code-SKILL.md), [website-testing](https://kookaburraadvies.nl/guides/advanced-agentic-website-design/files/website-testing-SKILL.md), and [website-security](https://kookaburraadvies.nl/guides/advanced-agentic-website-design/files/website-security-SKILL.md). Read each before use; review referenced scripts in third-party skills.
2. Each is a focused set of instructions. Read what you are asking Codex to follow.
3. If a third-party skill includes scripts, inspect those before running them.
4. The longer download names keep the files distinct; the final filename inside each folder is SKILL.md.
**You should now see:** You have read all four starter files before using them.
2. Ask Codex to prepare the [skill folders](#design-quality-skills-snippets). Move each download into its matching folder and rename it SKILL.md.
**Put each file in its folder**
Illustrated example: Illustration: each skill has its own folder and a separate file named SKILL.md.
- **Folder path:** fieldnotes-studio → .agents → skills → One folder per skill
- **Each file:** Matching skill folder → SKILL.md
**Look for:** All four skills exist at the exact paths shown in the folder structure.
Follow these steps if you want more help.
**Show the steps**
1. Follow the [project skill placement instructions](https://learn.chatgpt.com/docs/build-skills): inside fieldnotes-studio, create .agents/skills, then website-design, clean-code, website-testing, and website-security folders.
2. Use the [required folder structure](#design-quality-skills-snippets). Move each download to its matching folder and rename it SKILL.md, so every folder holds its own separate SKILL.md file.
3. Ask Codex to create only the four directories shown in Required skill structure, without building the website.
4. Move website-design-SKILL.md into .agents/skills/website-design, then rename it SKILL.md. Repeat in matching folders for the other three.
5. If .agents is hidden, use Finder Command + Shift + period or Windows View → Show → Hidden items. Ask Codex to compare the exact final paths.
**You should now see:** All four skills exist at the exact paths shown in the folder structure.
3. Check each SKILL.md starts with [name and description](https://agentskills.io/specification). Keep its name matched to its folder and save as plain text.
**Check each skill’s label**
Illustrated example: Illustration: check each skill&\#39;s name and description and match the name to its folder.
- **Check:** SKILL.md → name + description → Folder name matches
**Look for:** Each skill has valid name and description metadata and is saved as plain text.
Follow these steps if you want more help.
**Show the steps**
1. Check the [skill metadata specification](https://agentskills.io/specification). Retain name and description at the top, make each name match its folder, and save as plain text.
2. At the top, the metadata block has name and description between opening and closing --- lines.
3. Match the four names to their folders: website-design, clean-code, website-testing, website-security.
4. Keep the starter metadata unless you have a clear reason to change it; avoid long or conflicting instructions.
**You should now see:** Each skill has valid name and description metadata and is saved as plain text.
4. Start a new project chat and send the [four-skills check prompt](#design-quality-skills-prompts). Ask Codex to read each file and report missing ones.
**Check Codex can read them**
Illustrated example: Illustration: ask a fresh Codex chat to inspect all four skill files.
- **In Codex:** New chat → Copy four-skills prompt → Send
**Look for:** Codex reads all four files and explains when it will apply each workflow.
Follow these steps if you want more help.
**Show the steps**
1. Use the [skill discovery prompt](#design-quality-skills-prompts) in a fresh project chat. Codex detects changes automatically; restart if the files do not appear.
2. Compare the reported paths with the actual files. Ask for invalid or missing files rather than assuming they are correct.
3. Codex detects skill changes automatically; restart it if the files do not appear.
4. Check that fieldnotes-studio is the project&\#39;s primary folder. Discovery does not prove every workflow has been applied.
**You should now see:** Codex reads all four files and explains when it will apply each workflow.
5. Send the [design-skill prompt](#design-quality-skills-prompt-2). Name website-design directly and ask for a plan before implementation.
**Try the design skill**
Illustrated example: Illustration: explicitly invoke website-design and review its plan before implementation.
- **In Codex:** Copy design-skill prompt → Use website-design → Review plan
**Look for:** Explicit invocation produces a design-planning workflow you can review.
Follow these steps if you want more help.
**Show the steps**
1. Try the [explicit design-skill prompt](#design-quality-skills-prompt-2). Name the skill or file path directly; [official invocation guidance](https://learn.chatgpt.com/docs/build-skills) also covers optional CLI and IDE syntax.
2. The prompt gives .agents/skills/website-design/SKILL.md as its exact path.
3. Ask Codex to read it and explain the workflow&\#39;s outputs and review checks.
4. Review the plan before implementation. You can name the skill directly without using CLI or IDE selectors.
**You should now see:** Explicit invocation produces a design-planning workflow you can review.
6. Review the four files, then ask Codex to [commit the skill folders](https://git-scm.com/docs/git-commit). Save only the intended changes.
**Save the skills in Git**
Illustrated example: Illustration: review and commit the four intended skill files in Git.
- **Save:** Review .agents/skills → Stage the four files → Commit
**Look for:** Git records the four reviewed skills so collaborators can inspect the same instructions.
Follow these steps if you want more help.
**Show the steps**
1. Review all four files, then [save them as a Git commit](https://git-scm.com/docs/git-commit) so future collaborators can inspect the same instructions.
2. Show and inspect the four final paths before saving them.
3. Stage only the intended SKILL.md files, then review the staged diff.
4. Use a message such as Add website workflow skills. Keep unrelated pending changes separate; a commit does not prove website checks pass.
**You should now see:** Git records the four reviewed skills so collaborators can inspect the same instructions.
Basics, explained
**Skill**
A reusable set of task-specific instructions and optional resources that helps an agent follow a particular workflow.
**Metadata**
Short descriptive information at the start of a skill file, including its name and when it should be used.
**Explicit invocation**
Directly asking the agent to use a named skill, instead of waiting for it to choose the skill automatically.
**Hidden folder**
A folder file browsers may hide by default. Names beginning with a dot, such as .agents, are commonly hidden on macOS and Linux.
### Prompt: Check all four skills
```text
Inspect .agents/skills. Read the four SKILL.md files and confirm their names and paths. Explain when you will apply each workflow. Report invalid or missing files. Do not build or install tools yet.
```
### Prompt: Invoke the design skill
```text
Use website-design at .agents/skills/website-design/SKILL.md. Read it and apply its planning workflow to Fieldnotes Studio. Explain the concrete outputs and review checks before implementation.
```
### Required skill structure
```text
fieldnotes-studio/
AGENTS.md
.agents/
skills/
website-design/SKILL.md
clean-code/SKILL.md
website-testing/SKILL.md
website-security/SKILL.md
```
### Check your work
- [ ] All four files exist at the exact paths shown.
- [ ] Codex reads each file and explains its instructions.
- [ ] Explicit invocation produces the expected planning workflow, and Git records the files.
If something goes wrong
**.agents is hidden.**
In macOS Finder use Command + Shift + period. In Windows use View > Show > Hidden items where needed.
**Codex ignores the skill after naming it.**
Give its exact path. Ask Codex to read the file, list relevant requirements, and explain how the output meets them.
### Official links & further reading
- [Official Codex skill discovery and invocation](https://learn.chatgpt.com/docs/build-skills)
- [Open Agent Skills file specification](https://agentskills.io/specification)
## 8. Write your website brief
Phase: Plan
Tell Codex who your website is for, what it should do, and what belongs in the first version.
You do not need to describe every line of code. You do need to explain who the website serves, what those visitors need, and the action you want them to take. &\#39;Make it beautiful&\#39; leaves the agent guessing; &\#39;help a small-business owner understand my services and contact me&\#39; gives it a useful direction.
Fieldnotes Studio is our fictional example: a small design studio seeking enquiries. Its first version has four pages and a real contact email. Accounts, payments, a booking system, and an AI chatbot are future features with separate requirements. A small complete website is easier to review and maintain.
### Do this
1. Use the [brief example](#website-brief-snippets). Write who you help and what your business offers.
**Name your business and audience**
Illustrated example: Kooka illustrates name your business and audience: Business → Audience → What you offer.
- **Write:** Business → Audience → What you offer
**Look for:** One sentence describing your business and the people it serves.
Start with the [example website brief](#website-brief-snippets). Write one sentence describing your business, its primary audience, and the problem your site should help that audience solve.
**Step by step**
1. Open a plain-text note or ask Codex to draft a note from your words.
2. Write one sentence explaining your business, the people you help, and the problem you help solve.
3. Use Fieldnotes Studio only as a practice example; replace it with your own details for a real site.
**You should now see:** One sentence describing your business and the people it serves.
2. Choose one [main visitor action](https://developer.mozilla.org/en-US/docs/Learn_web_development/Getting_started/Your_first_website/What_will_your_website_look_like), such as emailing you about a project.
**Choose the main visitor action**
Illustrated example: Kooka illustrates choose the main visitor action: Visitor question → Useful answer → Contact.
- **Choose:** Visitor question → Useful answer → Contact
**Look for:** A clear action visitors can take after reading your site.
Use the [first-website planning questions](https://developer.mozilla.org/en-US/docs/Learn_web_development/Getting_started/Your_first_website/What_will_your_website_look_like) to choose one main visitor action. For Fieldnotes Studio, this is emailing the studio about a project; list what visitors need to know first.
**Step by step**
1. Imagine someone arriving at your site for the first time.
2. Write what they need to know before contacting you: what you offer, who it helps, and how to enquire.
3. For this practice site, choose an email enquiry as the main action.
**You should now see:** A clear action visitors can take after reading your site.
3. List Home, About, Services, and Contact in the [brief template](#website-brief-snippets). Put extra features under Later.
**Pick four pages**
Illustrated example: Kooka illustrates pick four pages: Home · About · Services · Contact → Later ideas.
- **Plan:** Home · About · Services · Contact → Later ideas
**Look for:** Four page names, each with one job; extra features saved for later.
Use the [brief template](#website-brief-snippets) to list Home, About, Services, and Contact. Give each page one purpose and put extra ideas in Later.
**Step by step**
1. Give Home the job of introducing your offer, About the people behind it, Services the help available, and Contact the enquiry route.
2. Move booking, payments, accounts, and AI chat features into Later.
3. Keep the first version small enough that you can read and test every page.
**You should now see:** Four page names, each with one job; extra features saved for later.
4. Add language, content, images, timing, and your own budget to the [brief template](#website-brief-snippets). Name the person who will maintain it.
**Set your limits**
Illustrated example: Kooka illustrates set your limits: Language → Content → Budget and timing → Owner.
- **Write:** Language → Content → Budget and timing → Owner
**Look for:** Your own spending limit and a named website owner.
Add language, content, images, spending preference, timing, and maintenance ownership to the [brief template](#website-brief-snippets). Set your own budget rather than accepting one invented by the agent.
**Step by step**
1. Add your preferred language and the text and permitted images you already have.
2. Set your own budget and target timing; do not let the agent invent a spending allowance.
3. Name who will update the site, and provide a real inbox you own and can test.
**You should now see:** Your own spending limit and a named website owner.
5. Copy the [brief prompt](#website-brief-prompts), replace the notes placeholder, and send it. Ask Codex to save docs/website-brief.md.
**Ask Codex to write the brief**
Illustrated example: Kooka illustrates ask codex to write the brief: Copy prompt → Add your notes → Send → docs/website-brief.md.
- **Codex:** Copy prompt → Add your notes → Send → docs/website-brief.md
**Look for:** A brief with your notes, visible assumptions, and missing content flagged.
Copy the [project-brief prompt](#website-brief-prompts), replace its notes placeholder, and send it. Ask for docs/website-brief.md with assumptions and content gaps before implementation.
**Step by step**
1. Open the linked prompt and use Copy prompt.
2. Replace the final notes placeholder with the notes you wrote in the previous actions.
3. Paste into the fieldnotes-studio chat and send. The task should create docs/website-brief.md and leave building for later.
**You should now see:** A brief with your notes, visible assumptions, and missing content flagged.
6. Read the brief, correct facts, and approve the scope. Ask Codex to [save a Git commit](https://git-scm.com/docs/git-commit).
**Review and save it**
Illustrated example: Kooka illustrates review and save it: Open brief → Correct facts → Approve scope → Commit.
- **Review:** Open brief → Correct facts → Approve scope → Commit
**Look for:** A saved brief you agree with, without invented claims or features.
Read the resulting brief, verify facts, answer essential questions, and remove unsupported features. [Commit the reviewed brief](https://git-scm.com/docs/git-commit) to record your planning decisions.
**Step by step**
1. Read docs/website-brief.md from beginning to end.
2. Correct business facts, answer essential questions, and remove invented prices, credentials, quotes, or unsupported features.
3. Ask Codex to show the changes and save the reviewed brief as a Git commit.
**You should now see:** A saved brief you agree with, without invented claims or features.
Basics, explained
**Brief**
A short written agreement describing the website&\#39;s purpose, audience, scope, and constraints.
**Scope**
The pages and features included in the version you are building.
**Call to action**
A clear invitation to do something, such as &\#39;Discuss your project&\#39; or &\#39;Email the studio&\#39;.
**Assumption**
Something the agent believes is true without having confirmed it. Mark assumptions so you can review them.
### Prompt: Create your project brief
```text
Turn my notes into docs/website-brief.md. Include purpose, primary audience, visitor needs, main call to action, four page purposes, first-version features, later features, content gaps, and constraints. Use Fieldnotes Studio as the practice example unless I provide my own business. Ask at most three essential questions; label other assumptions. Do not invent customer quotes, credentials, prices, or business claims. Do not build the website yet. My notes: [replace this sentence with your notes].
```
### A brief you can adapt
```text
Project: Fieldnotes Studio, a fictional design studio
Audience: Small-business owners considering design help
Goal: Help visitors understand our services and email us
Pages: Home / About / Services / Contact
First version: Static pages, mobile navigation, real email link
Later: Booking, payments, accounts, AI features
Content: Owner-approved copy and permitted images
Style: Calm, clear, editorial, easy to read
Budget and timing: Add your own constraints
Contact address: Provide an inbox you own and can test
```
### Check your work
- [ ] The brief names one primary audience, one main visitor action, and the four page purposes.
- [ ] First-version features and later ideas are listed separately, and assumptions are visible.
- [ ] You can judge whether a proposed page serves the brief without knowing how its code works.
If something goes wrong
**The brief grows into an elaborate app.**
Return to the single visitor action. Move features that do not support the four-page first version into &\#39;Later&\#39; and ask Codex to update the brief.
**You are unsure what the audience needs.**
Ask someone representative of that audience what they want to know before contacting you. Bring their answers back to the brief rather than inventing a visitor profile.
### Official links & further reading
- [MDN: plan a first website](https://developer.mozilla.org/en-US/docs/Learn_web_development/Getting_started/Your_first_website/What_will_your_website_look_like)
- [W3C: involve users when planning a website](https://www.w3.org/WAI/planning/involving-users/)
## 9. Plan your pages and content
Phase: Plan
Give every page a clear job. Gather the real words, images, and contact details Codex should use.
A useful visitor journey connects a question to an answer and then to an action. A Fieldnotes Studio visitor might arrive on Home, review Services, read About for context, and use Contact. Each page should work when reached directly from a shared link, too.
Real text changes a layout. A short sample heading may fit while your real service description does not. Prepare content early, and clearly mark anything still missing. The AI can improve wording, but you must verify business facts and approve what appears under your name.
### Do this
1. Send the [content-planning prompt](#sitemap-content-prompts). Ask Codex to save the four page addresses in docs/sitemap.md.
**Make a page map**
Illustrated example: Kooka illustrates make a page map: Copy prompt → Send → docs/sitemap.md.
- **Codex:** Copy prompt → Send → docs/sitemap.md
**Look for:** Home /, About /about/, Services /services/, and Contact /contact/.
Use the [content-planning prompt](#sitemap-content-prompts) to create docs/sitemap.md with /, /about/, /services/, and /contact/. Compare it with the [practice sitemap](#sitemap-content-snippets).
**Step by step**
1. Copy the linked prompt into your project chat.
2. Ask Codex to read the brief and create docs/sitemap.md.
3. Compare the addresses with the practice sitemap: /, /about/, /services/, and /contact/.
**You should now see:** Home /, About /about/, Services /services/, and Contact /contact/.
2. Write the visitor question, heading, sections, and next action for each page. Use [clear page headings](https://www.w3.org/WAI/tips/designing/).
**Give each page one job**
Illustrated example: Kooka illustrates give each page one job: Visitor question → Heading → Sections → Next action.
- **Plan:** Visitor question → Heading → Sections → Next action
**Look for:** Each page answers a different question and offers a sensible next action.
For each page, record its visitor question, heading, sections, and next action. Follow [clear headings and page structure guidance](https://www.w3.org/WAI/tips/designing/) so Home makes the business offer understandable.
**Step by step**
1. For each page, name the question a visitor wants answered.
2. Write its main heading and section headings in familiar language.
3. Choose the next useful action, such as viewing Services or opening Contact.
**You should now see:** Each page answers a different question and offers a sensible next action.
3. Use the [content-plan prompt](#sitemap-content-prompts) to save approved text and your real inbox in docs/content.md. Mark anything unfinished.
**Add your real content**
Illustrated example: Kooka illustrates add your real content: Approved text → Real inbox → docs/content.md → Mark gaps.
- **Codex:** Approved text → Real inbox → docs/content.md → Mark gaps
**Look for:** Your real information, with missing passages clearly marked.
Use the [content-plan prompt](#sitemap-content-prompts) to organise your approved description, services, biography, and real inbox in docs/content.md. Mark unfinished passages as editorial tasks.
**Step by step**
1. Gather your business description, services, biography, and real contact address.
2. Ask Codex to organise them in docs/content.md, using your supplied facts.
3. Mark unfinished sections as editorial tasks rather than accepting plausible-sounding invented details.
**You should now see:** Your real information, with missing passages clearly marked.
4. Collect images you may publish. Record sources and [useful image descriptions](https://www.w3.org/WAI/tutorials/images/decision-tree/) in docs/content.md.
**Choose permitted images**
Illustrated example: Kooka illustrates choose permitted images: Permitted image → Source → What it conveys.
- **Collect:** Permitted image → Source → What it conveys
**Look for:** A known source and useful description for every meaningful image.
Collect permitted images and record their source and purpose in docs/content.md. Use the [W3C image-alternative decision tree](https://www.w3.org/WAI/tutorials/images/decision-tree/) to describe what meaningful images convey.
**Step by step**
1. Check that you own each image or have permission to use it.
2. Record its source, permission notes, and the reason it belongs on the page.
3. Use the linked decision tree to choose meaningful alternative text; purely decorative images usually have empty alt text.
**You should now see:** A known source and useful description for every meaningful image.
5. Use [consistent navigation](https://www.w3.org/WAI/tips/designing/) for the header and footer. Add privacy information to the plan if your data practices need it.
**Choose the navigation**
Illustrated example: Kooka illustrates choose the navigation: Header links → Footer links → Privacy information if needed.
- **Choose:** Header links → Footer links → Privacy information if needed
**Look for:** The same page names in your plan and navigation.
Choose main navigation and footer links using [consistent navigation guidance](https://www.w3.org/WAI/tips/designing/). Review your actual data practices and add a privacy information page to the plan if needed before launch.
**Step by step**
1. Use the same short page names in the sitemap, header, and footer.
2. Check the actual site features and services for data collection.
3. Add clear privacy information to the plan where needed; review the content before launch.
**You should now see:** The same page names in your plan and navigation.
6. Ask someone unfamiliar with your business to [review the page sequence](https://www.w3.org/WAI/planning/involving-users/). Fix unclear words and missing answers.
**Try the page journey**
Illustrated example: Kooka illustrates try the page journey: Home → Services → About → Contact → Note unclear points.
- **Try:** Home → Services → About → Contact → Note unclear points
**Look for:** A reader can find the offer and contact route without your explanation.
Follow the idea of [involving visitors early](https://www.w3.org/WAI/planning/involving-users/): walk through the page sequence with someone unfamiliar with the business. Note unclear terms and missing answers, then update the content and sitemap.
**Step by step**
1. Walk through the planned pages with someone who does not already know your business.
2. Ask what remains unclear and how they would contact you.
3. Update docs/sitemap.md and docs/content.md with their questions and your corrections.
**You should now see:** A reader can find the offer and contact route without your explanation.
Basics, explained
**Sitemap**
Here, a planning list or diagram showing the pages and how they connect. A machine-readable XML sitemap comes later for search engines.
**Navigation**
The links and menus visitors use to move around a website.
**User journey**
The sequence of questions and actions a visitor follows to accomplish something.
**Alternative text**
A text description conveying the purpose of a meaningful image for people who cannot see it. Purely decorative images usually use empty alternative text.
### Prompt: Make the content plan
```text
Read docs/website-brief.md. Create docs/sitemap.md for Home, About, Services, and Contact, using /, /about/, /services/, and /contact/. For each page, list its visitor question, heading, sections, required content, and next action. Create docs/content.md with provided text, image sources, and clearly marked gaps. Recommend simple navigation. Do not invent testimonials or business facts, and do not build pages yet.
```
### Practice sitemap
```text
Home / What does the studio do?
About /about/ Who will I work with?
Services /services/ What help can I request?
Contact /contact/ How do I get in touch?
Main action: Discuss your project → Contact
Contact method: Email link to your verified inbox
```
### Check your work
- [ ] Every planned page answers a distinct visitor question and includes a sensible next action.
- [ ] The sitemap and navigation use the same page names and addresses.
- [ ] Content gaps are recorded; the contact address is real, and you know the source of every planned image.
If something goes wrong
**Two pages repeat the same information.**
Give each a clear job: Home introduces the offer, Services explains it, About provides context, and Contact enables the enquiry. Keep necessary short summaries and remove duplicated long passages.
**The agent inserts plausible-sounding customer quotes.**
Remove them unless they come from approved real source material. Ask Codex to flag missing proof rather than fabricate it.
### Official links & further reading
- [Astro: page files and addresses](https://docs.astro.build/en/basics/astro-pages/)
- [W3C: choosing useful image alternatives](https://www.w3.org/WAI/tutorials/images/decision-tree/)
- [W3C: clear navigation and page structure](https://www.w3.org/WAI/tips/designing/)
## 10. Choose a simple website setup
Phase: Plan
Use Astro to build four pages, CSS to style them, and a real email link for contact.
Astro is a website framework suited to content-focused sites. In this guide it generates ordinary HTML pages during a build. CSS controls their appearance, and a little browser JavaScript can handle interactions such as a mobile menu. Node runs the development and build tools on your computer.
The first version does not need user accounts, a database, or a server that handles private requests. A visible email address and mailto link let visitors contact you through their email application. An actual submission form needs a working receiving service or backend; drawing form fields alone does not deliver messages.
This is a deliberate teaching route for a small business website. If your brief requires payments, private accounts, or an AI feature, revisit the architecture and security requirements before treating this static setup as sufficient.
### Do this
1. Check your brief against [Astro’s approach](https://docs.astro.build/en/concepts/why-astro/). Confirm you need pages, without accounts or stored submissions.
**Keep the first version simple**
Illustrated example: Kooka illustrates keep the first version simple: Your brief → Four pages → Static website.
- **Choose:** Your brief → Four pages → Static website
**Look for:** A first version that needs no database or visitor account system.
Read the brief and [Astro&\#39;s content-focused approach](https://docs.astro.build/en/concepts/why-astro/). Confirm the first version needs only pages and browser interactions, without storing visitor accounts or submissions.
**Step by step**
1. Read the features in your first-version brief.
2. Confirm they can work as pages with small browser interactions and an email link.
3. If you need accounts, payments, private data, or an AI feature now, revise the architecture before using this route.
**You should now see:** A first version that needs no database or visitor account system.
2. Send the [architecture prompt](#technical-foundation-prompts). Ask Codex to save Astro, CSS, supported Node LTS, and npm in docs/architecture.md.
**Record the tools**
Illustrated example: Kooka illustrates record the tools: Copy prompt → Send → docs/architecture.md.
- **Codex:** Copy prompt → Send → docs/architecture.md
**Look for:** One framework and one package manager, with a supported Node version.
Use the [architecture prompt](#technical-foundation-prompts) to save docs/architecture.md with static Astro, CSS, Node LTS, and npm. Check [Astro setup requirements](https://docs.astro.build/en/install-and-setup/) and use one package manager.
**Step by step**
1. Copy the linked architecture prompt into Codex.
2. Ask it to check Astro’s current Node requirements and use one package manager: npm.
3. Review docs/architecture.md before any installation or scaffolding.
**You should now see:** One framework and one package manager, with a supported Node version.
3. Plan four page files and a shared header and footer using [Astro pages](https://docs.astro.build/en/basics/astro-pages/) and [layouts](https://docs.astro.build/en/basics/layouts/).
**Plan shared page parts**
Illustrated example: Kooka illustrates plan shared page parts: src/pages → Four pages → Shared header and footer.
- **Plan:** src/pages → Four pages → Shared header and footer
**Look for:** A plan naming four page files and a shared header and footer.
Record src/pages/index.astro, about.astro, services.astro, and contact.astro using [Astro page conventions](https://docs.astro.build/en/basics/astro-pages/). Plan a [shared layout](https://docs.astro.build/en/basics/layouts/), header, and footer.
**Step by step**
1. Record src/pages/index.astro, about.astro, services.astro, and contact.astro.
2. Plan a shared layout with the header and footer.
3. Explain to Codex that changes to shared navigation should appear consistently on every page.
**You should now see:** A plan naming four page files and a shared header and footer.
4. Plan a [mailto contact link](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a#linking_to_an_email_address) to your own inbox. Keep the address visible and copyable.
**Use a real email link**
Illustrated example: Kooka illustrates use a real email link: Visible email address → Email link → Visitor’s mail app.
- **Contact:** Visible email address → Email link → Visitor’s mail app
**Look for:** A real inbox visitors can copy or open in their mail app.
Specify the contact behavior using [email links in HTML](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a#linking_to_an_email_address): display your real inbox, open the visitor&\#39;s mail app, and keep the address copyable.
**Step by step**
1. Provide an inbox you own and can test.
2. Ask Codex to show the address as text and link it with mailto.
3. The link opens the visitor’s email app; it does not submit a message from the website itself.
**You should now see:** A real inbox visitors can copy or open in their mail app.
5. Treat a [working contact form](https://docs.astro.build/en/recipes/build-forms-api/) as an optional later feature. Record delivery, validation, abuse-control, and privacy requirements.
**Keep a form for later**
Illustrated example: Kooka illustrates keep a form for later: Form → Receiving service → Real delivery test.
- **Later:** Form → Receiving service → Real delivery test
**Look for:** A separate plan for a form; no fake success message.
Keep a functioning form as an optional advanced stage. Review [Astro&\#39;s backend form example](https://docs.astro.build/en/recipes/build-forms-api/) and record receiving-service, validation, abuse-control, delivery-testing, and privacy requirements.
**Step by step**
1. A drawn form cannot deliver messages by itself.
2. Before adding one, choose a receiving service or backend, server-side validation, abuse controls, and suitable privacy information.
3. Require a real delivery test and honest error states. Keep the email link until that work is complete.
**You should now see:** A separate plan for a form; no fake success message.
6. Ask Codex to explain [development, build, and preview](https://docs.astro.build/en/reference/cli-reference/). Finish the plan before building.
**Understand the three modes**
Illustrated example: Kooka illustrates understand the three modes: Develop locally → Build website files → Preview built files.
- **Learn:** Develop locally → Build website files → Preview built files
**Look for:** You can tell a live development preview from the last built version.
Ask Codex to explain [local development, building, and previewing](https://docs.astro.build/en/reference/cli-reference/). Compare its explanation with docs/architecture.md; leave implementation until the build stage.
**Step by step**
1. Development runs a local server that shows your ongoing edits.
2. A build creates the files your host will serve. Preview serves the last built version, so later changes need another build.
3. Check that docs/architecture.md explains this route; leave implementation until the build chapter.
**You should now see:** You can tell a live development preview from the last built version.
Basics, explained
**Frontend**
The website&\#39;s pages, styling, and interactions that visitors see and use in their browser.
**Framework**
A set of tools and conventions for organising and building a website or application.
**Static website**
A website served from files prepared during a build. It can still have browser interactions and link to external services.
**Build**
The process that turns project source files into the files a hosting service will serve to visitors.
### Prompt: Document the architecture
```text
Read the brief and sitemap. Save docs/architecture.md for a static Astro website using CSS, current supported Node LTS, and npm. List the four page files, shared layout, header, footer, image handling, and a real email-link contact method. Explain local development, build output, and hosting in beginner language. Keep accounts, payments, databases, and AI features out of this first version. Describe a backend contact form as a separate optional extension. Do not scaffold yet.
```
### Check your work
- [ ] The architecture file names one framework, one package manager, the four pages, and their shared elements.
- [ ] You can explain that Node builds the site and that visitors receive the generated files.
- [ ] The contact plan has a real delivery method; any form extension has explicit backend requirements.
If something goes wrong
**The agent proposes many frameworks and services.**
Ask it to justify each against the brief. Return to static Astro and npm for this four-page practice site; record any essential exception before adding it.
**A proposed form has a fake success message.**
Use the email-link version until a receiving service exists. Treat delivery, error states, and backend validation as required parts of implementing a real form.
### Official links & further reading
- [Astro&\#39;s purpose and content-focused approach](https://docs.astro.build/en/concepts/why-astro/)
- [Astro setup and supported Node versions](https://docs.astro.build/en/install-and-setup/)
- [Astro shared layouts](https://docs.astro.build/en/basics/layouts/)
- [Advanced option: Astro server rendering](https://docs.astro.build/en/guides/on-demand-rendering/)
## 11. Choose your website’s look
Phase: Plan
Pick a clear visual style. Review a Home-page sketch on a laptop and a phone before building it.
Design combines hierarchy, readability, navigation, imagery, and visual identity. A consistent type scale and spacing system usually help more than a pile of decorative effects. Fieldnotes Studio&\#39;s practice direction is calm and editorial: warm neutral surfaces, dark readable text, one restrained accent, and generous but purposeful space.
A wireframe is a rough arrangement of content. A visual concept adds typography, colour, and imagery. Both are decisions you can discuss before the agent spends time implementing them. Design references are useful for explaining qualities you admire; create your own composition and use assets you have permission to use.
### Do this
1. Choose two or three pages using [design planning guidance](https://developer.mozilla.org/en-US/docs/Learn_web_development/Getting_started/Your_first_website/What_will_your_website_look_like). Note what you like in docs/design-direction.md.
**Collect a few references**
Illustrated example: Kooka illustrates collect a few references: Two or three references → Specific notes → docs/design-direction.md.
- **Collect:** Two or three references → Specific notes → docs/design-direction.md
**Look for:** Notes on qualities you like, rather than instructions to copy a site.
Collect two or three reference pages using [MDN&\#39;s design planning guidance](https://developer.mozilla.org/en-US/docs/Learn_web_development/Getting_started/Your_first_website/What_will_your_website_look_like). Describe specific qualities you like and save URLs and notes to docs/design-direction.md.
**Step by step**
1. Save the URLs of two or three pages you admire.
2. Write specific notes: heading size, clear navigation, colours, spacing, or image style.
3. Create your own composition and use assets you have permission to publish.
**You should now see:** Notes on qualities you like, rather than instructions to copy a site.
2. Send the [visual-direction prompt](#visual-direction-prompts) using website-design. Ask for two options with your actual Home text and contact action.
**Ask for two directions**
Illustrated example: Kooka illustrates ask for two directions: Copy prompt → Two design options → Compare.
- **Codex:** Copy prompt → Two design options → Compare
**Look for:** Two practical options using your real content.
Use the [visual-direction prompt](#visual-direction-prompts) to invoke website-design. Ask for two directions based on your actual Home heading, services, and contact action.
**Step by step**
1. Open the linked prompt, copy it, and paste it into your project chat.
2. Name the website-design skill and ask Codex to read the brief, sitemap, content, and architecture.
3. Ask for two practical directions rather than many unrelated styles.
**You should now see:** Two practical options using your real content.
3. Compare Home sketches at both sizes using [accessible layout guidance](https://www.w3.org/WAI/tips/designing/). Can you find the offer and contact action?
**Review laptop and phone sketches**
Illustrated example: Kooka illustrates review laptop and phone sketches: Laptop sketch → Phone sketch → Offer and contact.
- **Review:** Laptop sketch → Phone sketch → Offer and contact
**Look for:** Both sizes explain the business and make contact easy to find.
Review laptop and phone Home wireframes with [accessible layout guidance](https://www.w3.org/WAI/tips/designing/) in mind. Check the first impression, services, and contact action; a sketch is sufficient to resolve structure.
**Step by step**
1. Use your actual heading, services, and contact action in the sketches.
2. Look at the first screen of both versions: is the offer clear?
3. Check that mobile rearranges content sensibly rather than shrinking the desktop layout.
**You should now see:** Both sizes explain the business and make contact easy to find.
4. Choose one option. Record colours, fonts, spacing, buttons, and image style using [design planning guidance](https://developer.mozilla.org/en-US/docs/Learn_web_development/Getting_started/Your_first_website/What_will_your_website_look_like).
**Save the design choices**
Illustrated example: Kooka illustrates save the design choices: Chosen option → Colours · Type · Space · Buttons → Design notes.
- **Save:** Chosen option → Colours · Type · Space · Buttons → Design notes
**Look for:** A small set of choices Codex can reuse across every page.
Choose one direction and record colours, fonts, sizes, spacing, content width, buttons, and image style. Use [design planning guidance](https://developer.mozilla.org/en-US/docs/Learn_web_development/Getting_started/Your_first_website/What_will_your_website_look_like) to keep the choices small and reusable.
**Step by step**
1. Choose one direction and tell Codex why it fits the brief.
2. Record the colours, font choices and sizes, spacing, content width, buttons, and image style.
3. Keep the choices small and reusable; save them in docs/design-direction.md.
**You should now see:** A small set of choices Codex can reuse across every page.
5. Check [readability, keyboard focus, and motion](https://www.w3.org/WAI/tips/designing/). Plan clear links, comfortable controls, and reduced-motion support.
**Include accessible behavior**
Illustrated example: Kooka illustrates include accessible behavior: Readable text → Visible focus → Comfortable controls → Reduced motion.
- **Check:** Readable text → Visible focus → Comfortable controls → Reduced motion
**Look for:** Accessibility choices are included before implementation.
Apply [W3C accessible design guidance](https://www.w3.org/WAI/tips/designing/): readable contrast, visible keyboard focus, clear link text, comfortable controls, and restrained motion that respects reduced-motion preferences.
**Step by step**
1. Check readable text contrast and clear link wording.
2. Include a visible focus outline for keyboard users and comfortably sized controls.
3. Keep movement restrained and respect reduced-motion preferences; record these decisions.
**You should now see:** Accessibility choices are included before implementation.
6. Ask someone to [review the concept](https://www.w3.org/WAI/planning/involving-users/). Fix unclear content, then approve the direction in docs/design-direction.md.
**Get a fresh pair of eyes**
Illustrated example: Kooka illustrates get a fresh pair of eyes: Business clear? → Offer clear? → Next action clear? → Update notes.
- **Review:** Business clear? → Offer clear? → Next action clear? → Update notes
**Look for:** A reader understands the business, offer, and next action.
Apply [visitor feedback principles](https://www.w3.org/WAI/planning/involving-users/) when reviewing the concept. Check whether the business, offer, and next action are clear; update docs/design-direction.md before approving implementation.
**Step by step**
1. Ask someone unfamiliar with your business what the page offers and what they would do next.
2. Note confusing language, missing answers, or a hard-to-find contact action.
3. Update docs/design-direction.md before approving implementation.
**You should now see:** A reader understands the business, offer, and next action.
Basics, explained
**Wireframe**
A simple sketch showing where content and controls belong before visual styling is final.
**Visual hierarchy**
The arrangement of size, spacing, and emphasis that tells a reader what matters first.
**Design system**
A reusable set of choices and elements, such as colours, typography, spacing, buttons, and navigation.
**Responsive design**
A layout that adapts to the available screen space, including phones and larger displays.
### Prompt: Explore the design
```text
Use the website-design skill and read our brief, sitemap, content, and architecture. Propose two distinct but practical visual directions for Fieldnotes Studio. Explain the hierarchy and create readable Home wireframes for laptop and phone widths using our actual copy. Include colour, typography, spacing, keyboard focus, image use, and reduced-motion decisions. Save the selected direction in docs/design-direction.md after my feedback. Do not implement the full site yet.
```
### Check your work
- [ ] The chosen direction is recorded with specific colours, typography, spacing, and reusable elements.
- [ ] Both the phone and laptop layouts keep the main offer and contact action understandable.
- [ ] Contrast, keyboard focus, and motion preferences are included in the design decisions.
If something goes wrong
**The concept looks attractive but the message is unclear.**
Replace the vague heading with a concrete description of the offer and make the contact action easy to recognise. Review again using your actual text.
**The phone version squeezes the desktop layout into a narrow column.**
Ask for a deliberate mobile arrangement: readable headings, adjusted spacing, simplified navigation, and images that preserve their subject.
### Official links & further reading
- [W3C: accessible visual design](https://www.w3.org/WAI/tips/designing/)
- [MDN: plan layout, colour, and content](https://developer.mozilla.org/en-US/docs/Learn_web_development/Getting_started/Your_first_website/What_will_your_website_look_like)
## 12. Plan small build stages
Phase: Plan
Ask Codex for a build plan with small tasks and checks you can see. Approve the first stage when ready.
A useful plan is more specific than &\#39;create pages, test, deploy&\#39;. It names the files or behavior to create, dependencies between tasks, and the evidence needed before moving on. Building one complete page first exposes design and setup problems before they spread across the website.
Acceptance criteria describe what you must be able to observe. For example, &\#39;all four navigation links reach their intended page&\#39; is verifiable. &\#39;The website is fully secure&\#39; is an unsupported absolute claim. Security and accessibility need relevant checks, documented findings, and clear limits.
### Do this
1. Send the [build-plan prompt](#implementation-plan-prompts). Ask Codex to read your instructions, skills, and planning files, and flag missing information.
**Check the planning files**
Illustrated example: Kooka illustrates check the planning files: Copy prompt → Read instructions and plans → Resolve questions.
- **Codex:** Copy prompt → Read instructions and plans → Resolve questions
**Look for:** Codex identifies missing or conflicting decisions before building.
Use the [implementation-plan prompt](#implementation-plan-prompts) to read AGENTS.md, planning documents, and skills. Ask Codex to flag conflicting decisions and essential missing information first.
**Step by step**
1. Open the linked prompt and paste it into your fieldnotes-studio chat.
2. Ask Codex to read AGENTS.md and the five planning files: website-brief.md, sitemap.md, content.md, architecture.md, and design-direction.md.
3. Use clean-code, website-testing, and website-security. Resolve essential gaps and conflicting choices before scaffolding.
**You should now see:** Codex identifies missing or conflicting decisions before building.
2. Ask Codex to save docs/build-plan.md using the [staged planning prompt](#implementation-plan-prompts). Build Home before the remaining pages.
**List the stages**
Illustrated example: Kooka illustrates list the stages: Setup → Home → Other pages → Checks → Later publication.
- **Plan:** Setup → Home → Other pages → Checks → Later publication
**Look for:** Small build stages, with publication kept separate.
Create docs/build-plan.md using the [staged planning prompt](#implementation-plan-prompts): setup, shared layout and Home, remaining pages, testing, security, polish, automated checks, and separate publication.
**Step by step**
1. Create stages for setup, shared layout and Home, remaining pages, testing, security, polish, and automated checks.
2. Complete Home before repeating the pattern on the other pages.
3. Keep publication as a separate later stage requiring your review and decision.
**You should now see:** Small build stages, with publication kept separate.
3. Ask for goals, files, dependencies, checks, and a saved Git milestone. Record [commands that actually exist](https://docs.astro.build/en/reference/cli-reference/).
**Give every stage a clear finish**
Illustrated example: Kooka illustrates give every stage a clear finish: Stage → Output → Check → Git milestone.
- **Write:** Stage → Output → Check → Git milestone
**Look for:** Each stage says what changes and how to verify it.
For each stage, record goals, files, dependencies, browser checks, and a Git milestone. Specify [real build and check commands](https://docs.astro.build/en/reference/cli-reference/) to establish or run; require honest reporting of failed or unavailable checks.
**Step by step**
1. For each stage, ask what it produces, which files it changes, and what it depends on.
2. Name the browser checks and actual build/check commands to establish or run.
3. Require honest reports of failed or unavailable checks and a reviewed Git milestone.
**You should now see:** Each stage says what changes and how to verify it.
4. Adapt the [acceptance checklist](#implementation-plan-snippets) for links, phone layout, keyboard focus, images, and contact. Use [W3C early checks](https://www.w3.org/WAI/test-evaluate/preliminary/).
**Use checks you can observe**
Illustrated example: Kooka illustrates use checks you can observe: Routes → Navigation → Phone → Keyboard → Contact.
- **Check:** Routes → Navigation → Phone → Keyboard → Contact
**Look for:** Checks describe things you can actually inspect.
Adapt the [example acceptance checklist](#implementation-plan-snippets) for routes, navigation, keyboard focus, phone readability, image alternatives, and real contact details. Use [W3C early accessibility checks](https://www.w3.org/WAI/test-evaluate/preliminary/) for observable evidence.
**Step by step**
1. Copy the example acceptance checklist and adapt it to your website.
2. Use observable checks: four routes load, links reach the intended pages, keyboard focus is visible, and mobile content does not overflow.
3. Include appropriate image alternatives, real contact details, and documented remaining issues.
**You should now see:** Checks describe things you can actually inspect.
5. Ask Codex to plan a successful build and useful tests, including any missing [package.json check scripts](https://docs.npmjs.com/cli/v11/using-npm/scripts/).
**Plan real automated checks**
Illustrated example: Kooka illustrates planning automated checks: name checks, create missing scripts during the build, then run and report results.
- **Plan:** Name checks → Create missing scripts during the build → Run and report results
**Look for:** The plan names the checks, when to create missing scripts, and how to report results.
Plan a successful [production build](https://docs.astro.build/en/reference/cli-reference/) and relevant automated checks. Include any missing [package.json scripts](https://docs.npmjs.com/cli/v11/using-npm/scripts/) as a build task; do not assume npm test already exists.
**Step by step**
1. Ask Codex to inspect package.json rather than assume npm test already exists.
2. Plan the tools and scripts required for useful code and browser checks.
3. Require a successful production build and browser inspection of the built version.
**You should now see:** The plan names the checks, when to create missing scripts, and how to report results.
6. Review the [acceptance checklist](#implementation-plan-snippets). Approve only the first build stage, then ask Codex to [commit the plan](https://git-scm.com/docs/git-commit).
**Approve the first stage**
Illustrated example: Kooka illustrates approve the first stage: Review plan → Approve first stage → Save → Build locally.
- **Decide:** Review plan → Approve first stage → Save → Build locally
**Look for:** You know the first task; publication still waits for later review.
Review the plan against the [acceptance checklist](#implementation-plan-snippets) and approve the first build stage only. Keep publication pending your later preview review, then [commit the planning milestone](https://git-scm.com/docs/git-commit).
**Step by step**
1. Read docs/build-plan.md and compare it with your brief and acceptance checklist.
2. Approve the first build stage when you understand its output and checks.
3. Ask Codex to commit the reviewed plan. Keep publication pending your later preview review.
**You should now see:** You know the first task; publication still waits for later review.
Basics, explained
**Acceptance criteria**
Specific conditions you can check to decide whether a feature or version is finished.
**Dependency**
Something a task needs before it can work, such as a shared layout before pages use that layout.
**Milestone**
A small, completed stage saved in Git so you have a known point to review or recover.
**Production build**
The output intended for hosting, created from the source. It needs verification in addition to the development preview.
### Prompt: Create an executable plan
```text
Read AGENTS.md and the five planning files in docs/: website-brief.md, sitemap.md, content.md, architecture.md, and design-direction.md. Use the clean-code, website-testing, and website-security skills. Save docs/build-plan.md with small stages, dependencies, intended files, meaningful acceptance criteria, required check scripts, browser checks, and Git milestones. Build Home completely before repeating patterns. Show conflicting assumptions and missing inputs. Keep deployment as a later approval step. Create the plan only; do not scaffold until I approve the first stage.
```
### Example acceptance criteria
```text
[ ] Home, About, Services, and Contact load at their planned URLs
[ ] Header and footer navigation reach the intended pages
[ ] Keyboard users can reach links and see focus
[ ] At 360px and 1280px, content has no horizontal overflow
[ ] Contact shows my real inbox and the matching email link
[ ] Images have appropriate alternatives and known sources
[ ] Established checks and the production build pass
[ ] Browser checks and remaining issues are documented
[ ] Publication awaits my approval after review
```
### Check your work
- [ ] Each planned stage has a concrete output and an observable completion check.
- [ ] The plan establishes missing scripts before using them, and includes browser inspection of the built site.
- [ ] You know the first task Codex will perform and where publication requires your decision.
If something goes wrong
**The plan promises quality without saying how to check it.**
Ask for evidence tied to each claim: routes tested, viewport widths inspected, commands run, security findings reviewed, and known limits recorded.
**Codex begins building while you are still reviewing the plan.**
Stop that task, inspect any changes, and restate the current boundary: finish the plan and wait for approval of the first build stage. Preserve useful changes before deciding how to proceed.
### Official links & further reading
- [Astro development, build, and check commands](https://docs.astro.build/en/reference/cli-reference/)
- [W3C: early accessibility checks](https://www.w3.org/WAI/test-evaluate/preliminary/)
- [W3C: integrate accessibility into project planning](https://www.w3.org/WAI/planning-and-managing/plan/)
## 13. Build your first page
Phase: Build & check
Let Codex build the Home page. Open it, check it, and save a working version.
Astro prepares ordinary website files from your project. Our example uses its static output: pages are generated before publication, so this first version needs neither a database nor an OpenAI API key on the website.
The installer creates the starting files. Codex should preserve the repository, instructions, skills, and brief you already prepared. A successful build is useful evidence, but does not prove that links, layout, or visitor journeys work. Begin browser checks now.
### Do this
1. Ask Codex to check your project and Node version against the [Astro requirements](https://docs.astro.build/en/install-and-setup/#prerequisites).
**Check your tools**
Illustrated example: Illustrated example: fieldnotes-studio → New chat → Ask to check the tools. Kooka points to the action.
- **In Codex:** fieldnotes-studio → New chat → Ask to check the tools
**Look for:** Codex confirms the right project and whether Node is supported.
Ask Codex to inspect the project folder and Node version before installing anything. Have it confirm that your supported Node LTS version meets the [current Astro installation requirements](https://docs.astro.build/en/install-and-setup/#prerequisites).
**Check before installing**
1. Open the fieldnotes-studio project in Codex. Start a chat within that project, so the agent works in the correct folder.
2. Ask: “Check the current branch and my Node and npm versions. Compare Node with Astro’s current requirements. Do not install anything yet.”
3. Read the result. If a tool is missing or unsupported, return to the computer-setup chapter and fix that before continuing.
**You should now see:** Codex confirms the right project and whether Node is supported.
2. Copy the [first-page prompt](#build-the-foundation-prompts) into Codex. Ask it to create the Astro starting files without overwriting your earlier work.
**Create the starting files**
Illustrated example: Illustrated example: Copy prompt → Paste → Send. Kooka points to the action.
- **In Codex:** Copy prompt → Paste → Send
- **Keep safe:** Existing Git history, instructions, skills, and notes
**Look for:** The project has Astro files and your earlier work is still there.
Use the [first-milestone prompt](#build-the-foundation-prompts) to scaffold a minimal Astro project. If the existing folder is unsuitable for the wizard, use a temporary scaffold. Exclude its .git folder, merge README.md and .gitignore instead of overwriting them, and preserve AGENTS.md, .agents/, and docs/.
**Preserve the existing project**
1. Open the linked prompt, click Copy prompt, then paste it into your fieldnotes-studio chat and send it.
2. The folder already contains Git history and instructions. If Astro needs an empty folder, Codex should create a temporary scaffold, then copy only the needed starting files.
3. Do not copy the temporary .git folder. Merge README.md and .gitignore rather than replacing them, and preserve AGENTS.md, .agents/, and docs/.
4. Ask Codex to list what it added and confirm that the existing branch, history, and planning files survived.
**You should now see:** The project has Astro files and your earlier work is still there.
3. Ask Codex to build Home using your brief and a [shared page layout](https://docs.astro.build/en/basics/layouts/). Use your real text and permitted images.
**Build Home**
Illustrated example: Illustrated example: Your brief → Shared layout → Home. Kooka points to the action.
- **Build request:** Your brief → Shared layout → Home
**Look for:** Home shows your approved offer and a clear way to contact you.
Ask Codex to create a [shared Astro page layout](https://docs.astro.build/en/basics/layouts/), header, footer, colours, typography, and the Home page from the approved brief. Use real copy and images you have permission to publish.
**Build one complete page**
1. Ask Codex to read docs/website-brief.md, docs/content.md, and the approved design direction before making the page.
2. Have it create the shared layout, header, footer, colours, and typography, then use them on Home.
3. Check that the text describes your real offer. Replace practice business details and use images you are allowed to publish.
**You should now see:** Home shows your approved offer and a clear way to contact you.
4. Ask Codex to add an [Astro code check](https://docs.astro.build/en/reference/cli-reference/#astro-check) and a [browser test](https://playwright.dev/docs/intro), then run them with the build.
**Add the first checks**
Illustrated example: Illustrated example: Check code → Test Home → Build. Kooka points to the action.
- **Ask Codex:** Check code → Test Home → Build
**Look for:** You have real check commands and a report showing what happened.
Have Codex inspect package.json, document the actual build and preview commands, and add an explicit [Astro code-check command](https://docs.astro.build/en/reference/cli-reference/#astro-check) and a first [Playwright browser smoke test](https://playwright.dev/docs/intro). It must install and configure any tools those checks need.
**Establish checks that really run**
1. Ask Codex to inspect package.json and document the build, preview, code-check, and test commands that actually exist.
2. Have it install and configure the required checking tools. The first browser test should open Home and check an important visible result.
3. Ask it to run the checks and build, show the actual results, and repair failures caused by this work. A successful build alone does not prove the page works.
**You should now see:** You have real check commands and a report showing what happened.
5. Open the [local preview](https://docs.astro.build/en/develop-and-build/). Check Home on a wide screen and a phone-sized screen.
**Open your preview**
Illustrated example: Illustrated example: Preview address → Browser → Wide and narrow screens. Kooka points to the action.
- **On your computer:** Preview address → Browser → Wide and narrow screens
**Look for:** Home opens locally and remains readable at both sizes.
Use the [local development, build, and preview instructions](https://docs.astro.build/en/develop-and-build/) to start the website. Open the address reported by the terminal, inspect Home at desktop and phone widths, then run the code check, browser test, and production build.
**Open the address Codex provides**
1. Ask Codex to start the local preview and give you the address reported by the running server. Click that address or copy it into your browser.
2. Review the heading, navigation, images, and contact action. Narrow the browser or use the browser’s device tools to inspect a phone-sized layout.
3. After the checks and build pass, also inspect the production preview. It serves the last built version, so rebuild after later changes.
**You should now see:** Home opens locally and remains readable at both sizes.
6. Review the changed files. Ask Codex to save a [Git commit](https://git-scm.com/docs/git-commit) after the page and checks work.
**Save this milestone**
Illustrated example: Illustrated example: Review changes → Run checks → Commit. Kooka points to the action.
- **Save process:** Review changes → Run checks → Commit
**Look for:** A named commit records your checked first page.
Review the changed files and save a [Git commit](https://git-scm.com/docs/git-commit) only after the first page passes these checks. Record any deliberately unfinished pages in the task list.
**Save a recoverable version**
1. Ask Codex to show the changed files and explain what each change does. Look for unrelated changes or accidental private information.
2. Confirm that the code check, browser test, build, and your own preview review are complete. Record unfinished pages in the task list.
3. Ask Codex to save the approved changes in a descriptive commit, such as “Build checked Home page”, and report its commit identifier.
**You should now see:** A named commit records your checked first page.
Basics, explained
**Scaffold**
The initial folders and files that give a new project a working starting point.
**Component**
A reusable piece of a page, such as the header. Updating one shared component updates every page that uses it.
**Smoke test**
A small automated check that catches basic breakage, such as a Home page that fails to load or loses its main heading.
### Prompt: Build the first milestone
```text
Read our brief, AGENTS.md, and relevant skills. Inspect this repository first. Scaffold a minimal static Astro site using the official current installer. If using a temporary scaffold, exclude its .git folder, merge README.md and .gitignore rather than overwrite them, and preserve existing Git history, AGENTS.md, .agents/, and docs/. Build only the shared foundation and Fieldnotes Studio Home page. Add a working local preview, explicit code diagnostics, and one meaningful browser smoke test. Document commands that actually exist in package.json. Run the checks and build, report their results, and give me the local address to inspect. Keep the site local.
```
### Official Astro installer; let Codex choose the safe destination
```sh
npm create astro@latest
```
### Standard scaffold commands; check package.json first
```sh
npm run dev
# Stop the dev server with Ctrl+C before using the same terminal again.
npx astro check
npm run build
npm run preview
```
### Check your work
- [ ] The local Home page loads with Fieldnotes Studio&\#39;s approved heading and content; your earlier instructions and Git history remain present.
- [ ] Codex shows a completed code check, a passing browser smoke test, and a successful build rather than simply saying the work is finished.
- [ ] The production preview opens after the build, and Home is usable at both desktop and phone widths.
If something goes wrong
**The terminal reports that Node is unsupported.**
Compare node --version with the current Astro prerequisites. Install a supported LTS release using the setup instructions, restart the terminal, and retry.
**The preview address does not open.**
Check whether the terminal still shows a running server and which address it reports. Restart the dev server if it stopped; an occupied port can change the address.
### Official links & further reading
- [Astro: install and set up a project](https://docs.astro.build/en/install-and-setup/)
- [Astro: develop, build, and preview](https://docs.astro.build/en/develop-and-build/)
- [Astro: code-check commands](https://docs.astro.build/en/reference/cli-reference/#astro-check)
## 14. Finish the other pages
Phase: Build & check
Build About, Services, and Contact. Keep the same design and check each page as you go.
Astro turns files in src/pages/ into website addresses. For example, about.astro provides the About page. Codex can explain the file-to-address relationship while creating the pages; you do not need to memorise the code.
For the first release, Contact will show your real email address and an email link. A mailto link opens the visitor&\#39;s configured email app; the visitor still chooses whether to send the message. A website form needs a real receiving service and verified delivery. A success animation alone proves nothing about delivery.
### Do this
1. Use your [page plan](#sitemap-content) to give About, Services, and Contact one clear job each.
**Plan the next pages**
Illustrated example: Illustrated example: Page purpose → Real content → Next action. Kooka points to the action.
- **Your notes:** Page purpose → Real content → Next action
**Look for:** Each remaining page has a clear task and approved content.
Use the [page and content plan](#sitemap-content) to create a task for each remaining page with its purpose, approved copy, images, and intended next action. Replace example business details with your own before publication.
**Keep the page tasks small**
1. Open docs/sitemap.md and docs/content.md with Codex. Make a separate task for About, Services, and Contact.
2. For each task, name the page’s purpose, its approved text and images, and the next action visitors should take.
3. Replace fictional business details with your own. Keep missing content visible in the task list rather than asking Codex to invent it.
**You should now see:** Each remaining page has a clear task and approved content.
2. Ask Codex to [create a branch](https://git-scm.com/docs/git-switch) named codex/remaining-pages, starting from your checked Home page.
**Start a new branch**
Illustrated example: Illustrated example: Checked Home → codex/remaining-pages. Kooka points to the action.
- **Ask Codex:** Checked Home → codex/remaining-pages
**Look for:** Your new branch includes the working Home page.
Ask Codex to [create a new Git branch](https://git-scm.com/docs/git-switch) for the current milestone, named codex/remaining-pages, and confirm that its starting point contains the checked Home page.
**Keep a known starting point**
1. First confirm that the checked Home page was saved in a commit. Ask Codex to report the current branch and any unsaved changes.
2. Ask it to create codex/remaining-pages from that working version. It should preserve your current files and history.
3. Ask Codex to confirm the branch name and that Home still opens. A branch lets you review this milestone separately.
**You should now see:** Your new branch includes the working Home page.
3. Build About and Services with the [shared layout](https://docs.astro.build/en/basics/layouts/). Open and review each before continuing.
**Build the next pages**
Illustrated example: Illustrated example: Build About → Review → Build Services → Review. Kooka points to the action.
- **Page by page:** Build About → Review → Build Services → Review
**Look for:** Both pages open and use the same header, footer, and style as Home.
Build About and Services using the [shared Astro layout](https://docs.astro.build/en/basics/layouts/). Review each in the local browser before moving to the next task.
**Reuse the first page’s foundation**
1. Ask Codex to build About from its task and the shared layout. Open the local page and check the text, images, and next action.
2. Give concrete feedback, such as “this heading is too long on my phone”. Let Codex fix it and rerun the affected checks.
3. Repeat for Services. Review both pages when opened directly by their addresses, as well as through navigation.
**You should now see:** Both pages open and use the same header, footer, and style as Home.
4. Build Contact with your visible email address and a matching [email link](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links#email_links).
**Add a real contact method**
Illustrated example: Illustrated example: Show your address → Email link → Your email app. Kooka points to the action.
- **On Contact:** Show your address → Email link → Your email app
**Look for:** Visitors can copy your address or open a message addressed to you.
Build Contact with a visible, copyable email address and a matching [mailto email link](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links#email_links). Add the same navigation and footer to every page, plus a useful missing-page screen.
**Use the simple email route first**
1. Give Codex an inbox you own and can test. Ask it to show the address as selectable text and create a matching mailto link.
2. Click the link on a device with an email app configured. Check the recipient address; the visitor still chooses whether to send.
3. Keep the copyable address as a fallback. Add shared navigation and a useful missing-page screen so visitors can find their way back.
**You should now see:** Visitors can copy your address or open a message addressed to you.
5. Try the phone menu with touch and a keyboard, using the [accessibility checks](https://www.w3.org/WAI/test-evaluate/preliminary/).
**Try the phone menu**
Illustrated example: Illustrated example: Open menu → Choose a page → Close menu. Kooka points to the action.
- **Touch:** Open menu → Choose a page → Close menu
- **Keyboard:** Tab to controls → Activate → Check focus
**Look for:** You can open, use, and close the menu without losing your place.
If the design needs a mobile menu, check opening, closing, focus, and navigation using touch and keyboard, using the [W3C accessibility checks](https://www.w3.org/WAI/test-evaluate/preliminary/). Ask Codex to remove interactions that add complexity without helping visitors.
**Check any menu the design uses**
1. Open the phone-sized preview. Tap the menu, choose a page, then reopen it and try its close control.
2. Put the mouse aside and use the keyboard. Check a visible focus outline, a sensible order, and a way out of the open menu.
3. Tell Codex the exact action that failed and what you expected. If a menu adds complexity without helping visitors, simplify it.
**You should now see:** You can open, use, and close the menu without losing your place.
6. Run the checks, review the changes, and save a [commit](https://git-scm.com/docs/git-commit) for each completed milestone.
**Check and save**
Illustrated example: Illustrated example: Run checks → Review changes → Commit. Kooka points to the action.
- **After a page:** Run checks → Review changes → Commit
**Look for:** The finished pages have check evidence and saved milestones.
Run the existing checks after each completed milestone, review the changed files, and save a descriptive [Git commit](https://git-scm.com/docs/git-commit). If you choose a backend form later, use the [visitor-testing chapter](#test-as-a-visitor) to plan a separate milestone with a real endpoint, validation, failure handling, spam controls, and a test message received in your inbox.
**Keep progress reviewable**
1. Ask Codex to run the configured checks after each milestone. Inspect the changed files and open the affected pages yourself.
2. Save a descriptive commit once the work is checked. Keep unfinished tasks and failed checks in the report.
3. A backend form is an optional later milestone. It needs a real receiving endpoint, server-side validation, spam controls, error states, and a message received in your inbox; a success animation alone is insufficient.
**You should now see:** The finished pages have check evidence and saved milestones.
Basics, explained
**Route**
An address within your website, such as /services/. Each route should lead to the page visitors expect.
**Branch**
A separate line of saved work where you can develop a change before bringing it into the main version.
**mailto link**
A link that asks the visitor&\#39;s email app to start a message to an address. It does not itself send or store that message.
### Prompt: Complete the next page
```text
Use the approved Fieldnotes Studio brief and shared design to complete the next unfinished page. Explain which route and files you will change. For Contact, use the real address I supply, show it as selectable text, and create a matching mailto link. Reuse shared components, check desktop and mobile behaviour, and run the existing checks. Report what changed and any remaining tasks. Keep the work on our milestone branch and prepare a descriptive commit for review.
```
### Check your work
- [ ] Home, About, Services, and Contact each open directly, and every navigation link leads to the expected page.
- [ ] The Contact address matches the intended inbox. Its link opens a message to that address where an email app is configured; the address remains usable by copying it.
- [ ] The milestone has a descriptive commit and a check report. Optional form work is complete only when a real test message arrives.
If something goes wrong
**Clicking the email link does nothing on one computer.**
Check that an email app or webmail handler is configured. Keep the address visible so visitors can copy it into their preferred email service.
**A navigation link produces a missing-page error.**
Give Codex the exact failing address and expected page. Ask it to compare the link with the actual page route, fix the mismatch, and retest it.
### Official links & further reading
- [Astro: pages and routes](https://docs.astro.build/en/basics/astro-pages/)
- [MDN: creating email links](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links#email_links)
- [GitHub: pull requests and reviewing branch changes](https://docs.github.com/en/pull-requests/reference/pull-requests)
## 15. Try the website as a visitor
Phase: Build & check
Follow the links, use the phone menu, and try the keyboard. Ask Codex to repeat the important checks.
Playwright can operate a browser and check an expected result. Useful tests describe what a visitor accomplishes: navigating from Home to Services, finding Contact, or operating the mobile menu. Avoid tests that merely confirm that the code contains the same text Codex just wrote.
Automated accessibility checks detect some problems, including certain missing labels and contrast failures. They cannot establish complete accessibility. Keyboard use, readable content, zoom, meaningful image descriptions, and screen-reader checks need human judgement too.
### Do this
1. Use the [test prompt](#test-as-a-visitor-prompts) to plan three journeys through the site. Say what should happen at each step.
**Choose the journeys**
Illustrated example: Illustrated example: Home → Services → Contact. Kooka points to the action.
- **Main journey:** Home → Services → Contact
- **Also try:** About → Contact, plus the phone menu
**Look for:** Three short journeys each have an expected outcome.
Use the [visitor-journey test prompt](#test-as-a-visitor-prompts) to turn three journeys into test cases: Home to Services to Contact; direct arrival on About to Contact; and opening the navigation on a phone. State the expected result for each.
**Test a visitor goal**
1. Write the main journey: arrive on Home, find Services, and reach Contact. State the page or result you expect after each action.
2. Also test arriving directly on About and finding Contact, plus opening and using the phone menu.
3. Give these journeys to Codex through the linked prompt. Ask for checks of visible behaviour, not tests that merely repeat the code.
**You should now see:** Three short journeys each have an expected outcome.
2. Ask Codex to configure and run [Playwright tests](https://playwright.dev/docs/intro) for your journeys, using a [local test server](https://playwright.dev/docs/test-webserver).
**Repeat the checks automatically**
Illustrated example: Illustrated example: Set up browser tests → Run journeys → Show results. Kooka points to the action.
- **Ask Codex:** Set up browser tests → Run journeys → Show results
**Look for:** The test report shows which journeys passed or failed.
Ask Codex to extend the first smoke test into [Playwright browser tests](https://playwright.dev/docs/intro) for these journeys. Have it configure a [local test server](https://playwright.dev/docs/test-webserver), install the required browsers, and document the exact test command.
**Let the browser test perform real actions**
1. Ask Codex to extend the first smoke test into checks for your three visitor journeys.
2. Have it install the required browsers, configure the local test server, and document the actual test command. Prefer the built preview where practical.
3. Run the tests and read the results. Ask for reproducible evidence of a failure rather than accepting an unsupported “it works”.
**You should now see:** The test report shows which journeys passed or failed.
3. Resize the preview and try a phone, using [Chrome device mode](https://developer.chrome.com/docs/devtools/device-mode) when helpful.
**Try different screen sizes**
Illustrated example: Illustrated example: Wide → Tablet width → Phone width. Kooka points to the action.
- **In the browser:** Wide → Tablet width → Phone width
**Look for:** You can read and use the site without sideways scrolling.
Test the production preview at narrow phone, tablet, and desktop widths, using [Chrome device-mode instructions](https://developer.chrome.com/docs/devtools/device-mode) when needed. Also try a real phone when available; watch for hidden controls, overflowing text, cropped images, and unwanted sideways scrolling.
**Inspect what changes when space is tight**
1. Open the production preview at a wide desktop size. Narrow the browser and inspect the tablet and phone layouts.
2. Use the linked Chrome device-mode instructions if you want a controlled phone-sized viewport. Also try a real phone when available.
3. Look for clipped headings, hidden buttons, awkwardly cropped images, and sideways scrolling. Give Codex the page and screen width when reporting a problem.
**You should now see:** You can read and use the site without sideways scrolling.
4. Put the mouse aside. Use Tab and Enter to try every control, following the [keyboard-access checks](https://www.w3.org/WAI/test-evaluate/preliminary/).
**Use only the keyboard**
Illustrated example: Illustrated example: Tab → See focus → Enter. Kooka points to the action.
- **Key path:** Tab → See focus → Enter
- **Move back:** Shift + Tab
**Look for:** Each control is reachable, usable, and visibly focused.
Use the [W3C keyboard-access checks](https://www.w3.org/WAI/test-evaluate/preliminary/) with the mouse aside. Press Tab and Shift+Tab to move through controls, Enter to activate links, and the menu&\#39;s supported keyboard controls. Check visible focus, sensible order, and whether you can escape any open interface.
**Check where the keyboard takes you**
1. Start at the browser address bar and press Tab to move into the page. Use Shift+Tab to move backwards.
2. Check that an outline or another clear indicator shows which link or control has focus. Press Enter to activate links and use each menu’s supported controls.
3. Check the order and whether you can leave every open interface. Record the exact key sequence if focus disappears or becomes trapped.
**You should now see:** Each control is reachable, usable, and visibly focused.
5. Zoom to 200% and check headings and images with the [accessibility guide](https://www.w3.org/WAI/test-evaluate/preliminary/). Ask Codex to add [axe checks](https://playwright.dev/docs/accessibility-testing).
**Check reading and accessibility**
Illustrated example: Illustrated example: Zoom to 200% → Read → Check headings and image text. Kooka points to the action.
- **In the browser:** Zoom to 200% → Read → Check headings and image text
**Look for:** Your report includes manual findings and automated accessibility results.
Follow the [W3C first accessibility review](https://www.w3.org/WAI/test-evaluate/preliminary/): zoom to 200%, review page titles and heading order, and check meaningful image descriptions. Ask Codex to add [axe-based accessibility tests](https://playwright.dev/docs/accessibility-testing) alongside Playwright; automated results still need manual review.
**Combine direct inspection with automated checks**
1. Zoom the browser to 200%. Check that the page remains readable and that important controls still work.
2. Review distinct page titles, a sensible heading order, and descriptions that convey useful images. Decorative images should not add unnecessary noise.
3. Ask Codex to run axe-based tests and explain their findings. Automated checks cannot establish full accessibility; record keyboard, zoom, and other manual findings too.
**You should now see:** Your report includes manual findings and automated accessibility results.
6. Save a report using the [chapter checks](#test-as-a-visitor-checks). Ask Codex to fix failures and try those checks again.
**Record, fix, and retry**
Illustrated example: Illustrated example: Expected result → Actual result → Fix and retry. Kooka points to the action.
- **Your report:** Expected result → Actual result → Fix and retry
**Look for:** Failures are reproducible, and fixes have been checked again.
Save a short report using the [chapter success checks](#test-as-a-visitor-checks): page, device or viewport, action, expected result, actual result, and status. Have Codex reproduce failures, fix them, and rerun affected checks. For a backend form, test both real delivery and rejected or failed submissions.
**Keep useful evidence**
1. Record the page, device or viewport, action, expected result, actual result, and status. This tells Codex how to reproduce the problem.
2. Ask Codex to fix confirmed defects and rerun the affected checks. Do not weaken assertions or remove findings just to get a passing report.
3. For the email link, check the recipient rather than claiming a message was sent. Any optional backend form needs separate real delivery evidence and rejected or failed submission checks.
**You should now see:** Failures are reproducible, and fixes have been checked again.
Basics, explained
**End-to-end test**
A test that follows an action through the working system to its outcome, such as submitting a form and confirming that the receiving service got it.
**Viewport**
The visible area of a browser page. A narrow viewport helps reveal problems that appear on phones.
**Keyboard focus**
The control that currently receives keyboard input. A visible focus indicator helps people see where they are on the page.
**Regression**
Something that previously worked but breaks after a later change. Repeatable tests help catch it.
### Prompt: Test meaningful visitor journeys
```text
Read the acceptance criteria and existing test setup. Use Playwright to test the Fieldnotes Studio journeys Home > Services > Contact, About > Contact, and mobile navigation. Check observable behaviour with meaningful assertions. Add an axe accessibility scan and explain its limits. Run against the built preview where practical. Report actual results and save reproducible failures; do not weaken assertions to get a pass. Fix confirmed defects, then rerun the affected checks. Give me a separate manual keyboard and zoom checklist.
```
### Check your work
- [ ] The test report lists actual passing or failing results for all three journeys, with reproducible instructions for any failures.
- [ ] Every interactive control is reachable and usable by keyboard, with a visible focus indicator and no keyboard trap.
- [ ] Content remains readable at phone widths and 200% zoom; automated accessibility results and remaining manual findings are both recorded.
- [ ] A mailto action is checked as a correctly addressed email link. Any optional website form has separate evidence of actual receipt and failure handling.
If something goes wrong
**Playwright cannot connect to the website.**
Have Codex check the configured server command, port, and base URL against the actual preview. Ensure the build exists and the required browser is installed.
**The automated scan passes, but keyboard navigation is confusing.**
Record the precise sequence of keys and the unexpected focus movement. Fix the control behaviour and check it manually again; an automated pass does not override that finding.
### Official links & further reading
- [Playwright: installation and first tests](https://playwright.dev/docs/intro)
- [Playwright: starting the test web server](https://playwright.dev/docs/test-webserver)
- [Playwright: accessibility testing with axe](https://playwright.dev/docs/accessibility-testing)
- [W3C: first accessibility checks](https://www.w3.org/WAI/test-evaluate/preliminary/)
## 16. Review security and privacy
Phase: Build & check
Ask Codex what it checked, what it found, and what still needs attention. Keep the evidence.
Our static example has no visitor accounts, database, or AI endpoint. Its risks still include exposed secrets, vulnerable build dependencies, unwanted third-party scripts, and account access. Adding forms, payments, or accounts creates extra systems that need their own review.
A security skill guides the agent&\#39;s work; it is not a security certificate. npm audit reports known dependency vulnerabilities and also has limits. Ask what was examined and what remains unverified, rather than accepting a universal claim that the site is secure.
### Do this
1. Use the [security-review prompt](#review-security-and-privacy-prompts) to list the site’s features, services, accounts, and data.
**List what needs review**
Illustrated example: Illustrated example: Pages → Services → Accounts → Data. Kooka points to the action.
- **Start with:** Pages → Services → Accounts → Data
**Look for:** The review has a clear scope based on your actual website.
Use the [scoped security-review prompt](#review-security-and-privacy-prompts) to ask Codex to list the actual site features, dependencies, external services, data collected, and privileged accounts. Include hosting logs and email enquiries, even when the pages themselves are static.
**Review the systems you really use**
1. Ask Codex to inventory pages, dependencies, third-party scripts, external services, and accounts with privileged access.
2. Include hosting logs and email enquiries in the data list, even though the website uses static pages.
3. Keep accounts, databases, AI endpoints, and forms out of the inventory unless they actually exist. Adding any later requires a separate review.
**You should now see:** The review has a clear scope based on your actual website.
2. Ask Codex to check files and history for [exposed secrets](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html). Revoke any leaked credential with its provider.
**Check for exposed keys**
Illustrated example: Illustrated example: Revoke it → Replace if needed → Clean up the exposure. Kooka points to the action.
- **If a key leaked:** Revoke it → Replace if needed → Clean up the exposure
**Look for:** Suspected secrets are reported without their values; exposed keys are disabled.
Review tracked files, Git history, and the generated dist folder for secrets, using [OWASP secret-management guidance](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html). Require a report that identifies locations without printing credential values. If a key was exposed, revoke or rotate it with its provider; deleting the current file alone is insufficient.
**Deleting a file does not disable a key**
1. Have Codex inspect tracked files, relevant Git history, and the generated dist output. Reports should name locations and credential types without printing secret values.
2. If a real credential was exposed, open its provider’s account controls and revoke or rotate it. Do not paste the value into the chat.
3. Then review use of the old key and follow a scoped cleanup plan. Deleting the newest file or adding .gitignore does not erase old history or revoke access.
**You should now see:** Suspected secrets are reported without their values; exposed keys are disabled.
3. Run [npm audit](https://docs.npmjs.com/cli/v11/commands/npm-audit/). Ask Codex to explain the findings, fix relevant issues, and rerun the checks.
**Review package findings**
Illustrated example: Illustrated example: npm audit → Review findings → Fix and retest. Kooka points to the action.
- **With Codex:** npm audit → Review findings → Fix and retest
**Look for:** Each relevant finding has a fix or a recorded assessment.
Run [npm audit](https://docs.npmjs.com/cli/v11/commands/npm-audit/) and have Codex explain each relevant advisory, affected component, and proposed fix. Apply reviewed updates on a branch, then rebuild and rerun tests. Avoid automatic forced upgrades without understanding their impact.
**Assess before upgrading**
1. Ask Codex to run npm audit and explain the advisory, affected package, and likely impact for this project.
2. Apply compatible, scoped updates on a branch. Avoid automatic forced upgrades that may change behaviour or break the build.
3. Rebuild and rerun relevant tests. Record any unresolved issue and what remains unverified; npm audit covers known dependency advisories, not every possible risk.
**You should now see:** Each relevant finding has a fix or a recorded assessment.
4. List outside services and collected data. Use the [EU information guidance](https://commission.europa.eu/law/law-topic/data-protection/information-business-and-organisations/obligations_en) to prepare accurate privacy information where it applies.
**Explain the data flow**
Illustrated example: Illustrated example: Website → Service provider → Privacy information. Kooka points to the action.
- **Trace the data:** Website → Service provider → Privacy information
**Look for:** The privacy content describes the real services and data handling.
Inspect external scripts, embeds, fonts, and analytics. Keep only those you need. Record which providers receive visitor data and use their actual settings plus the [EU personal-data information guidance](https://commission.europa.eu/law/law-topic/data-protection/information-business-and-organisations/obligations_en) to prepare an accurate privacy notice where applicable.
**Use actual settings and providers**
1. Inspect scripts, embeds, fonts, and analytics with Codex. Remove what the site does not need.
2. Record which providers receive information, what it is used for, and the actual retention settings. Include business email enquiries and hosting logs.
3. Prepare privacy information matching these facts and the applicable requirements. A code scan or AI-written notice alone does not establish legal compliance.
**You should now see:** The privacy content describes the real services and data handling.
5. If you added a form, check its [server-side validation](https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html) and verify a real test message arrives.
**Check any optional form**
Illustrated example: Illustrated example: Submit → Server checks → Verify receipt. Kooka points to the action.
- **Only if you added a form:** Submit → Server checks → Verify receipt
**Look for:** A form has receiving-service safeguards and real delivery evidence, or is recorded as not applicable.
If you added a receiving form service, use [OWASP server-side input-validation guidance](https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html) to require sensible input and length checks, alongside spam controls and failure handling. Recheck real delivery; browser-only validation can be bypassed. Keep credentials in the receiving service&\#39;s secure configuration.
**This action is conditional**
1. The first version uses an email link. If there is no backend form, record this part as not applicable.
2. For a real form, require server-side input and length validation, spam controls, protected credentials, and useful failure states. Browser validation can be bypassed.
3. Use an authorised test destination to verify actual receipt, plus invalid input and delivery failures. A website success message alone is insufficient.
**You should now see:** A form has receiving-service safeguards and real delivery evidence, or is recorded as not applicable.
6. Save the dated review. Use the [chapter checks](#review-security-and-privacy-checks) to track fixes, open findings, and remaining decisions.
**Keep the review report**
Illustrated example: Illustrated example: Scope → Evidence → Open issues → Next action. Kooka points to the action.
- **Report contents:** Scope → Evidence → Open issues → Next action
**Look for:** The report records what was checked and what remains unresolved.
Save the dated report and review the [security and privacy success checks](#review-security-and-privacy-checks). Fix unresolved high-impact findings before release, record the owner of remaining decisions, and use the [EU disclosure guidance](https://commission.europa.eu/law/law-topic/data-protection/information-business-and-organisations/obligations_en) to review personal-data information where it applies.
**Make the result reviewable**
1. Save a dated report covering review scope, methods, evidence, findings, fixes, and unavailable or unverified areas.
2. Fix unresolved high-impact issues before release. Name an owner for remaining decisions and retain the evidence from checks after fixes.
3. Review personal-data disclosures where applicable. Avoid absolute statements such as “fully secure” or “legally compliant” based on this review.
**You should now see:** The report records what was checked and what remains unresolved.
Basics, explained
**Dependency**
Software your project relies on, such as Astro or a testing library. Its bugs and vulnerabilities can affect your project.
**Secret rotation**
Replacing a credential and disabling the old one, so a copied or leaked old value no longer grants access.
**Server-side validation**
Checking submitted data in the receiving service before accepting it. Checks in the visitor&\#39;s browser are useful but can be skipped.
### Prompt: Produce a scoped security report
```text
Use the website-security skill to review the actual Fieldnotes Studio implementation. Inventory features, dependencies, external services, and personal-data flows. Examine tracked files, relevant Git history, and dist for secrets without printing their values. Run npm audit and explain relevant findings. For any backend form, review server-side validation, abuse controls, credentials, and error handling. Write a dated report with evidence, severity, fixes, and unverified areas. Apply safe, scoped fixes and rerun checks. Do not claim complete security or legal compliance.
```
### Report known dependency vulnerabilities without changing packages
```sh
npm audit
```
### Check your work
- [ ] The report identifies what was reviewed, the results, unresolved findings, and any areas that require further expertise or information.
- [ ] No credentials are present in the published output or tracked files; any discovered exposed credentials have been disabled or replaced.
- [ ] Dependency findings have documented fixes or assessed remaining risk, with successful checks after changes.
- [ ] The privacy content describes actual data handling and providers. Optional forms have both server-side safeguards and delivery evidence.
If something goes wrong
**Codex reports a leaked credential.**
Disable or replace it through the provider, then remove the exposure and review its use. Ask Codex for a scoped cleanup plan; do not paste the credential into the chat.
**npm audit offers a forced update that may break the site.**
Ask for the advisory and a compatible remediation plan. Test the proposed change on a branch and record any unresolved issue before deciding whether release is appropriate.
### Official links & further reading
- [npm: audit commands and limits](https://docs.npmjs.com/cli/v11/commands/npm-audit/)
- [OWASP: managing secrets](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html)
- [OWASP: validating input](https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html)
- [European Commission: explaining personal-data processing](https://commission.europa.eu/law/law-topic/data-protection/information-business-and-organisations/obligations_en)
## 17. Make the site faster and clearer
Phase: Build & check
Improve loading, page titles, and the final details. Check the result again after each change.
Large images and unnecessary scripts can make an otherwise simple website slow. Astro provides image tools, but Codex still needs to choose appropriate dimensions, loading behaviour, and descriptions for each image.
Search engine optimisation helps search systems interpret useful pages. Clear titles, descriptive links, and accurate content are a sensible starting point. A technical checklist cannot promise rankings or visitors. Lighthouse offers lab measurements and suggestions; its score can vary with test conditions.
### Do this
1. Open the built preview in Chrome. Run a mobile [Lighthouse audit](https://developer.chrome.com/docs/lighthouse/overview/) and save its report.
**Run a page audit**
Illustrated example: Illustrated example: Inspect → Lighthouse → Mobile → Run audit. Kooka points to the action.
- **In Chrome:** Inspect → Lighthouse → Mobile → Run audit
**Look for:** You have a report for the latest built page, with its test conditions recorded.
Build the latest version and start its production preview. Follow the [Chrome Lighthouse instructions](https://developer.chrome.com/docs/lighthouse/overview/) to open Developer Tools, select Lighthouse, and run a mobile audit. Save the report and record the tested page and conditions.
**Audit the version you intend to publish**
1. Ask Codex for a fresh build and production preview, then open its reported address in Chrome.
2. Right-click part of the page and choose Inspect to [open Developer Tools](https://developer.chrome.com/docs/devtools/open). Select Lighthouse, choose Mobile, and run the page-load audit; button wording can vary.
3. Save the report or record its findings. Note the page and conditions so later comparisons are useful.
**You should now see:** You have a report for the latest built page, with its test conditions recorded.
2. Give Codex the report and the [polish prompt](#polish-speed-and-search-prompts). Ask for the three most useful improvements.
**Choose what to fix**
Illustrated example: Illustrated example: Share report → Ask for priorities → Review the plan. Kooka points to the action.
- **In Codex:** Share report → Ask for priorities → Review the plan
**Look for:** The next fixes have clear benefits for visitors.
Use the [visitor-focused polish prompt](#polish-speed-and-search-prompts) to have Codex explain the largest practical issues in plain language. Prioritise slow main images, unnecessary browser scripts, inaccessible text, and content shifts over cosmetic score changes.
**Choose useful improvements**
1. Give Codex the saved report or its important findings. Use the linked prompt with your current preview and approved design.
2. Ask it to explain three practical priorities in everyday language: for example, a slow main image, unnecessary browser code, unreadable text, or content that moves while loading.
3. Agree on focused fixes. Lighthouse is a lab measurement whose score can vary; do not treat one score as a guarantee or change the design merely to chase it.
**You should now see:** The next fixes have clear benefits for visitors.
3. Ask Codex to optimise images with [Astro’s image tools](https://docs.astro.build/en/guides/images/). Compare the page before and after.
**Improve the images**
Illustrated example: Illustrated example: Original image → Optimised file → Inspect the page. Kooka points to the action.
- **Compare:** Original image → Optimised file → Inspect the page
**Look for:** Images load appropriately and keep their intended subject and space.
Have Codex use [Astro image tools](https://docs.astro.build/en/guides/images/) to optimise sizes and formats, reserve space for images, and keep the important first image from being delayed unnecessarily. Compare the page before and after.
**Keep image quality and layout in view**
1. Have Codex choose suitable image sizes and formats for where each image is displayed.
2. Reserve space for images so the layout does not jump. Avoid delaying the important first image unnecessarily.
3. Inspect the result at phone and desktop sizes. Compare loading evidence and appearance, then rerun the affected checks.
**You should now see:** Images load appropriately and keep their intended subject and space.
4. Use the [SEO guide](https://developers.google.com/search/docs/fundamentals/seo-starter-guide) to give every page an accurate title, description, and headings.
**Name each page clearly**
Illustrated example: Illustrated example: Accurate title → Useful description → Clear headings. Kooka points to the action.
- **For every page:** Accurate title → Useful description → Clear headings
**Look for:** Page information matches its actual content.
Use the [Google SEO starter guide](https://developers.google.com/search/docs/fundamentals/seo-starter-guide) to give each page a distinct, accurate title and description. Review headings, descriptive links, image descriptions, and social sharing information against the real content.
**Help people and search systems understand pages**
1. Ask Codex to review Home, About, Services, and Contact. Each should have a distinct title and an accurate description.
2. Check heading order, descriptive links, meaningful image descriptions, and social-sharing information against the real content.
3. Read the words yourself. Technical SEO supports understanding but cannot promise rankings or visitor numbers.
**You should now see:** Page information matches its actual content.
5. Once you know the public address, ask Codex to use it in the [sitemap and canonical URLs](https://developers.google.com/search/docs/fundamentals/seo-starter-guide).
**Use the real public address**
Illustrated example: Illustrated example: Your public address → Page URLs → Sitemap. Kooka points to the action.
- **When known:** Your public address → Page URLs → Sitemap
**Look for:** Public page addresses use the chosen domain, or remain an explicit task until it is known.
Ask Codex to prepare the sitemap and canonical URLs using the intended public address once it is known, following the [search-visibility guidance](https://developers.google.com/search/docs/fundamentals/seo-starter-guide). Keep unfinished or private draft content out of public output; search exclusion is not access protection.
**Do not invent the final address**
1. Give Codex the intended public website address when it is confirmed. If it is still unknown, keep this as a recorded launch task.
2. Ask it to set the sitemap and canonical URLs to that address. Check for localhost, invented domains, or old addresses.
3. Keep private or unfinished content out of the published output. Search exclusion does not provide access protection.
**You should now see:** Public page addresses use the chosen domain, or remain an explicit task until it is known.
6. Follow the [visitor checklist](#test-as-a-visitor-checks) once more. Fix final problems and save the checked milestone.
**Review the finished pages**
Illustrated example: Illustrated example: Check four pages → Fix details → Rerun checks → Save. Kooka points to the action.
- **Final pass:** Check four pages → Fix details → Rerun checks → Save
**Look for:** The polished site still passes its visitor checks and has a saved milestone.
Use the [visitor-testing checklist](#test-as-a-visitor-checks) to inspect Home, About, Services, and Contact at phone and desktop widths. Remove placeholder copy, verify business details and image permissions, then rerun affected checks and save the polished milestone.
**Finish the practical details**
1. Inspect all four pages at phone and desktop widths. Remove placeholder copy, verify business details, and confirm image permissions.
2. Look for distorted images, cropped content, unreadable controls, and unexpected sideways scrolling.
3. Ask Codex to rerun the checks affected by the polish work. Review the latest built preview and save the checked version in Git.
**You should now see:** The polished site still passes its visitor checks and has a saved milestone.
Basics, explained
**SEO**
Search engine optimisation: making useful content and page structure easier for search engines to discover and understand.
**Canonical URL**
The preferred public address of a page, used to clarify which version should represent that content.
**Layout shift**
Content unexpectedly moving while a page loads, for example when an image appears without space reserved for it.
### Prompt: Fix the issues that matter to visitors
```text
Review the latest Fieldnotes Studio production preview and this Lighthouse report. Explain the three most useful improvements for visitors, then implement focused fixes for image loading, unnecessary JavaScript, layout stability, and readable content. Review each page's title, description, headings, links, and sharing metadata. Prepare sitemap and canonical settings using the public URL I supply; flag any unknown address instead of inventing one. Rerun relevant checks and compare evidence. Keep the approved visual direction and report remaining limitations.
```
### Check your work
- [ ] The latest built preview has a saved Lighthouse report, with concrete improvements or explained remaining findings.
- [ ] Every page has an accurate title and description, and canonical or sitemap addresses contain no invented domain or localhost address.
- [ ] The website has no unfinished placeholder copy, distorted images, unreadable controls, or unexpected horizontal scrolling in the reviewed layouts.
- [ ] Existing visitor-journey checks still pass after the optimisations.
If something goes wrong
**The preview still shows the old content.**
Stop the preview, run a fresh build, and start the preview again. It serves the last generated output, while the development server updates during editing.
**A performance score changes between runs.**
Compare tests under similar conditions and inspect the specific reported issues. Use repeated measurements to evaluate a meaningful change rather than treating one score as a guarantee.
### Official links & further reading
- [Chrome: run Lighthouse audits](https://developer.chrome.com/docs/lighthouse/overview/)
- [Astro: image handling and optimisation](https://docs.astro.build/en/guides/images/)
- [Google: SEO starter guide](https://developers.google.com/search/docs/fundamentals/seo-starter-guide)
## 18. Review the site and set up automatic checks
Phase: Publish & maintain
Get a fresh review, fix the problems, and make GitHub repeat the checks whenever your code changes.
A pull request lets you compare a proposed change with the saved main version. You review it before joining the two versions.
GitHub Actions runs your agreed checks automatically. A passing run is useful evidence, but you still decide whether the site is ready.
### Do this
1. Copy the [fresh-review prompt](#review-and-automate-checks-prompts) into a new Codex chat. Ask it to compare the changes with your [project requirements](#implementation-plan).
**Ask for a fresh review**
Illustrated example: Illustration: open a new Codex chat, send the review prompt, and compare its report with the project requirements.
- **In Codex:** New chat → Paste review prompt → Read report
- **Then:** Compare requirements and changed files.
**Look for:** A separate review report with findings you can check.
Use a new conversation so the review starts by inspecting the work.
**Show the review steps**
1. Open a new chat in the same Codex project. Copy Request a fresh review from the prompts below and send it with the branch name, your brief and the test report.
2. Ask the reviewer to inspect the changed files and reproduce suspected problems. Compare the result with your acceptance criteria from chapter 12.
3. A separate AI chat is still an AI review. Arrange a suitable human review for work you cannot judge, especially accounts, payments or personal data.
**You should now see:** A report separating confirmed defects, questions and limits. The reviewer does not modify files or merge the branch.
2. Fix confirmed problems and repeat the affected [visitor checks](#test-as-a-visitor-checks). Keep any remaining findings in your review note.
**Fix and check again**
Illustrated example: Illustration: a reported problem leads to a small fix and a repeat of the relevant visitor tests.
- **Work loop:** Confirm the problem → Fix it → Repeat the affected checks
**Look for:** Confirmed defects have fixes and new check results. Open findings stay visible.
A finding is useful when you can show what fails and check the repair.
**Work through the findings**
1. Ask Codex to reproduce each reported defect before changing it. Fix one clear problem at a time.
2. Repeat the affected tests and the important visitor journeys from chapter 15. Record what was checked and the result.
3. Keep unanswered questions in the release note. If a serious problem remains, keep the release as a draft.
**You should now see:** Confirmed release-blocking defects are fixed, with new check evidence. Unresolved findings remain recorded.
3. Use the [quality-workflow prompt](#review-and-automate-checks-prompt-2) to add [automatic GitHub checks](https://docs.github.com/en/actions/tutorials/build-and-test-code/nodejs). Use commands that already work on your computer.
**Save the automatic checks**
Illustrated example: Illustration: Codex creates quality.yml from the project commands that already work locally.
- **In the project:** .github → workflows → quality.yml
- **Ask Codex:** Use the verified install, code-check and build commands.
**Look for:** A workflow file that repeats the actual project checks without publishing the site.
A workflow is a saved list of commands for GitHub to run.
**Make your working checks repeatable**
1. Copy [Make the verified checks repeatable](#review-and-automate-checks-prompt-2). Have Codex inspect package.json, the committed lockfile and the supported Node version.
2. Ask for .github/workflows/quality.yml to run on pushes and pull requests. Use npm ci and the real check and build commands already verified locally.
3. Use current official GitHub actions and minimal read permissions. This static website does not need an OpenAI API key in the workflow. Do not add automatic deployment.
**You should now see:** The saved workflow uses real project commands, the intended Node version and no unnecessary credentials.
4. Include [Playwright browser checks](https://playwright.dev/docs/ci) and reports that help you understand failures.
**Include the browser tests**
Illustrated example: Illustration: install the test browsers, run the website tests, and save a report when a check fails.
- **Workflow:** Install browsers → Start test site → Run tests → Save reports
**Look for:** The workflow can run the intended browser tests and preserve useful failure evidence.
The browser tests need their own browsers and a website to visit.
**Prepare the browser test job**
1. Follow Playwright’s current CI instructions to install the browsers and their required system packages.
2. Have Codex use the project’s working test configuration to start the local test site and run the intended browser checks.
3. Save failure reports, logs and useful screenshots. They help you investigate a failed check rather than guess what happened.
**You should now see:** Browser tests can run on GitHub, with useful evidence retained when a check fails.
5. Push your branch and [open a pull request](https://docs.github.com/en/pull-requests/how-tos/create-pull-requests/creating-a-pull-request). Read the Actions run for its latest change.
**Open a pull request**
Illustrated example: Illustration: create a GitHub pull request, open Actions, and read the logs for the latest commit.
- **On GitHub:** Your branch → Compare & pull request → Create Pull Request
- **Read the checks:** Actions → Latest run → Job log
**Look for:** A pull request and a completed check run for its latest commit.
A pull request keeps the proposed changes together for review.
**Find the pull request and its results**
1. Save your branch changes as commits, then push that branch to your GitHub repository.
2. On GitHub, choose the branch and Compare & pull request. Check that the base is your main branch and the compare branch is your work, then use Create Pull Request.
3. Open the repository’s Actions tab and inspect the latest run. Read any failed job’s log. Confirm the run belongs to the latest pull-request commit, rather than an older version.
**You should now see:** The pull request shows completed check results for the change you are actually reviewing.
6. Check [Actions usage](https://docs.github.com/en/billing/concepts/product-billing/github-actions), then review the results. Merge only after the relevant checks pass and you approve the change.
**Review before merging**
Illustrated example: Illustration: inspect the review report and check results before choosing whether to merge the change.
- **Decision:** Read findings → Check the latest results → Approve or keep working
**Look for:** You approve only a reviewed change whose relevant checks pass.
Green checks help your decision; they do not make the decision for you.
**Decide whether to merge**
1. Review GitHub Actions usage and any charges for your account. You do not need API access just to run this static site’s checks.
2. Read the separate review report and the latest build and browser results. Address serious findings before approving the change.
3. Merge only when you approve the reviewed result. In this tutorial, hosting uses a later manual upload; this workflow has no website deployment job. If you add automatic hosting later, check its release triggers before merging.
**You should now see:** The main version contains only the change you approved after relevant checks passed.
Basics, explained
**Diff**
A comparison that highlights what was added, changed, and removed between two versions of the files.
**CI**
Continuous integration: automatically running agreed checks as code changes, so broken changes are caught before release.
**Lockfile**
A file recording dependency versions. npm ci uses it to reproduce the installation and fails when it disagrees with package.json.
**Workflow**
A saved sequence of jobs and commands, triggered by events such as a push or pull request.
### Prompt: Request a fresh review
```text
Review the Fieldnotes Studio branch diff against our brief and acceptance criteria. Independently inspect functionality, accessibility, secrets, dependencies, and test coverage. Reproduce suspected defects and cite affected files. Distinguish confirmed issues from questions and limitations. Report findings without modifying files or merging the branch.
```
### Prompt: Make the verified checks repeatable
```text
Inspect package.json, the lockfile, Node requirements, and our working browser test configuration. Create .github/workflows/quality.yml for push and pull_request using official current GitHub Actions, minimal read permissions, npm ci, and the actual verified code-check, build, and browser-test commands. Configure required Playwright browser installation and failure artifacts. No OpenAI API key is required for this static site. Explain each job and how I inspect its results on GitHub. Do not add automatic website deployment.
```
### Check your work
- [ ] A separate review report exists, and confirmed release-blocking findings have fixes with check evidence.
- [ ] The pull request shows a completed Actions run for the latest commit, including the intended build and browser checks.
- [ ] The workflow contains real project commands, appropriate Node settings, and no plaintext credentials or unnecessary API access.
If something goes wrong
**The workflow says a script is missing.**
Compare the failing command with package.json. Have Codex correct the workflow or explicitly configure and verify the intended script locally before rerunning.
**Tests work locally but fail on GitHub.**
Read the failing job&\#39;s log and saved browser evidence. Check Node compatibility, browser installation, server startup, case-sensitive paths, and lockfile consistency.
### Official links & further reading
- [GitHub: pull requests](https://docs.github.com/en/pull-requests/reference/pull-requests)
- [GitHub Actions: build and test Node.js](https://docs.github.com/en/actions/tutorials/build-and-test-code/nodejs)
- [Playwright: continuous integration](https://playwright.dev/docs/ci)
- [GitHub: Actions billing and usage](https://docs.github.com/en/billing/concepts/product-billing/github-actions)
## 19. Publish your site and check it online
Phase: Publish & maintain
Publish only after your review. Then check the real web address and practise returning to an older version.
Hosting puts a built copy of your website online. This tutorial uses Netlify and a manual upload; reading this draft does not publish anything.
An uploaded address may be public or private, depending on the account settings. Check the setting before uploading or sharing your site.
### Do this
1. Create or sign in to [Netlify](https://app.netlify.com/). Read its [plans and usage terms](https://www.netlify.com/pricing/) and set up [two-factor authentication](https://docs.netlify.com/manage/accounts-and-billing/user-settings/#enable-two-factor-authentication-2fa).
**Prepare the hosting account**
Illustrated example: Illustration: sign in to Netlify, read the plan, and enable two-factor authentication.
- **Account:** Sign in → Review plan → User settings → Security → Two-factor authentication
**Look for:** You can access the intended hosting account and understand its usage terms.
Hosting has its own account, costs and recovery information.
**Prepare your account**
1. Create or sign in to the Netlify account you intend to keep. Read the current plan and usage terms instead of assuming every feature is free.
2. In User settings, open Security, then Two-factor authentication. Follow the setup with your authenticator app.
3. Save the recovery codes in a protected place such as your password manager, separate from the website files. Confirm you can find them.
**You should now see:** Your hosting account is accessible, protected and recoverable.
2. Copy the [release-preparation prompt](#publish-and-verify-prompts). Review the built website and its check results before approving publication.
**Review the release first**
Illustrated example: Illustration: check the local built site and its test report before approving an upload.
- **In Codex:** Copy release prompt → Build → Preview → Review results
- **Decision:** Approve this release before uploading.
**Look for:** A reviewed build, check report and recorded release version, ready for your decision.
Approve the files that will be uploaded, not only the source code.
**Prepare everything locally**
1. Copy the release-preparation prompt below. Have Codex prepare the release locally and wait for your explicit instruction before uploading or changing DNS.
2. Run a fresh build of the reviewed commit, open the production preview and repeat the important checks. Ask Codex to identify the actual output folder; it is usually dist for this static Astro example.
3. Inspect that folder for unfinished private material, credentials and accidental source files. Save the reviewed commit, built output and check report before deciding whether to publish.
**You should now see:** A reviewed release package and check report. Nothing is published by this preparation.
3. When you approve the release, use [Netlify Drop](https://app.netlify.com/drop) to upload the built folder. Check [project visibility](https://docs.netlify.com/manage/security/secure-access-to-sites/project-visibility/) before sharing it.
**Upload the approved website**
Illustrated example: Illustration: the approved dist folder goes to Netlify Drop, followed by a check of who can open the site.
- **Upload:** Signed-in Netlify Drop → Approved built folder
- **Check access:** Project configuration → General → Visitor access → Project visibility
**Look for:** The approved website is uploaded and you know who can open its address.
Uploading is a real release step. Check access settings first.
**Upload the right folder**
1. Check the team’s visibility defaults before uploading. New credit-plan teams may default to private, while older teams may default to public. If you cannot confirm private access, treat the upload as potentially public.
2. Only after you approve the release, sign in to the intended Netlify team and open Netlify Drop. Upload the built output folder, such as dist, containing the generated website files.
3. Inspect Project configuration → General → Visitor access → Project visibility. Open the assigned address in a private browser window to see what a visitor without your sign-in can access. Do not upload the entire repository or credentials.
**You should now see:** A deploy of the approved built files, with its actual visibility confirmed.
4. Keep the supplied address, or optionally follow the [domain setup](https://docs.netlify.com/manage/domains/get-started-with-domains/) instructions. Preserve existing email records and verify [HTTPS](https://docs.netlify.com/manage/domains/secure-domains-with-https/https-ssl/).
**Choose your web address**
Illustrated example: Illustration: choose between the supplied netlify.app address and an optional domain you own, while preserving email records.
- **Keep it simple:** Use the supplied netlify.app address.
- **Optional:** Add your domain → Configure DNS → Verify HTTPS
**Look for:** The chosen address works over HTTPS; existing email settings are preserved.
A custom domain is optional. You can keep the supplied address.
**Choose the address without disrupting email**
1. If you own a domain and want to use it, add it to the Netlify project, then follow the instructions for your DNS provider. Check which records serve business email before changing anything.
2. Preserve email records and follow the HTTPS verification instructions. Wait for the stated DNS update time; do not repeatedly change records while waiting.
3. Use the final address in the website’s canonical and sitemap settings. Rebuild and recheck, then upload the updated built folder through the existing project’s Deploys page.
**You should now see:** The chosen HTTPS address is reflected in the site settings and built files, with email records preserved.
5. When you approve public access, repeat the [live-site checks](#publish-and-verify-checks) on the final HTTPS address. Record the released version and results.
**Test the public website**
Illustrated example: Illustration: approve public access if needed, open the website, and test pages and the Contact action.
- **If still private:** Review again → Make public
- **Then:** Open final HTTPS address → Test all pages and Contact → Record release
**Look for:** The actual public website passes the visitor checks you performed, with results recorded.
A local check cannot show every difference introduced by hosting.
**Check the actual public release**
1. If the approved site is still private, use Make public when you are ready. If it is already public, start the live checks straight away.
2. In a private browser window, open the final HTTPS address. Enter each page’s address directly. Check navigation, missing pages, images, phone layout and the Contact email link. If you added a form, confirm a fresh test message is received.
3. Record the public address, commit, deploy identifier, date and results. Confirm that canonical URLs and the sitemap use that final address.
**You should now see:** A release record connects the live website to the uploaded version and its actual check results.
6. Prepare a [two-version test site](#publish-and-verify-prompt-2). Practise [restoring an older deploy](https://docs.netlify.com/deploy/manage-deploys/manage-deploys-overview/#rollbacks), then restore the latest version.
**Practise going back**
Illustrated example: Illustration: on a test site, select an older successful deploy, publish it, and then restore the latest successful version.
- **Prepare:** Version 1 → New test project → Version 2 in the same project
- **On a test site:** Deploys → Previous successful deploy → Publish Deploy
- **Finish:** Restore the latest successful version → Record recovery steps
**Look for:** You have practised recovery on a test site and retained your own release copy.
First create a disposable practice project with two versions. Use its separate address for this exercise.
**Create the two-version test site**
1. Send the [practice-site prompt](#publish-and-verify-prompt-2) to Codex. Open each generated index.html and check that one says version 1 and the other says version 2.
2. Sign in to your intended Netlify team. At the bottom of its [Projects page](https://docs.netlify.com/deploy/create-deploys/#drag-and-drop), drop the version-1 folder to create a new project. Check its address differs from your real site; do not attach your domain.
3. Open that test project’s Deploys page. Drop the version-2 folder into its upload area. This updates the same project. Confirm two successful deploys appear and the test address now shows version 2.
**Try the rollback**
1. In the test project’s Deploys list, open the older successful deploy and choose [Publish Deploy](https://docs.netlify.com/deploy/manage-deploys/manage-deploys-overview/#rollbacks). Visit the test address and check it now shows version 1.
2. Publish the latest successful deploy again. Check the same address shows version 2. Record these recovery steps for your real website.
3. Keep an independent copy of your real website’s release. Hosted versions can expire or be removed; a later automatic deploy can replace a rolled-back version.
**You should now see:** Documented recovery, practised on a test site, plus an independent copy of the known working release.
Basics, explained
**Deployment**
Publishing a particular built version of the website to its hosting service.
**DNS**
The records that tell the internet where a domain&\#39;s website, email, and other services live.
**HTTPS**
An encrypted browser-to-site connection backed by a certificate. It protects that connection, but does not prove that the whole website is safe.
**Rollback**
Restoring an earlier working release when the latest one has a problem.
### Prompt: Prepare the release for my review
```text
Prepare a release checklist for this static Fieldnotes Studio site using Netlify's current manual-upload instructions. Confirm the reviewed commit, actual output folder, passing checks, and absence of secrets or unfinished private material in the output. Explain how I upload dist, inspect the resulting public address, configure my chosen domain without damaging email DNS, verify HTTPS, and restore a retained previous deploy. Record unknown settings as questions. Prepare everything locally and wait for my explicit instruction before any publication or DNS changes.
```
### Prompt: Prepare a disposable rollback test
```text
Prepare a tiny rollback practice site locally. Create two separate folders named version-1 and version-2 inside a new temporary folder called rollback-practice. Each must contain a standalone index.html: the first clearly says “Rollback practice — version 1”; the second says “Rollback practice — version 2”. Use only these words and simple styling, with no website content, credentials, forms, tracking, external services or dependencies. Do not overwrite existing files or change the real website. Keep these practice files out of Git commits. Tell me exactly where both folders are and how to open each index.html to check the labels. Prepare the files only; do not upload anything, create a hosting project or change a domain.
```
### Check your work
- [ ] The final HTTPS address opens without a certificate warning and all four pages work when their addresses are entered directly.
- [ ] The live visitor journeys, phone navigation, images, and Contact action work; optional forms have a newly received test message.
- [ ] Canonical URLs and the sitemap use the chosen public address, and the release record identifies the uploaded version.
- [ ] Recovery instructions are documented and were practised on a test site; an independent copy of the release is retained.
If something goes wrong
**The uploaded site is blank or missing pages.**
Check that you uploaded the latest generated output folder containing the built HTML. Inspect the local production preview and hosting deploy log before rebuilding and replacing the upload.
**The domain works inconsistently or HTTPS is pending.**
Check domain verification and DNS against the current host instructions. Preserve email records, allow the stated DNS update time, and use the host&\#39;s HTTPS troubleshooting instead of repeatedly changing records.
### Official links & further reading
- [Netlify: create manual deploys](https://docs.netlify.com/deploy/create-deploys/#drag-and-drop)
- [Netlify: add and configure a domain](https://docs.netlify.com/manage/domains/get-started-with-domains/)
- [Netlify: HTTPS certificates](https://docs.netlify.com/manage/domains/secure-domains-with-https/https-ssl/)
- [Netlify: manage deploys and roll back](https://docs.netlify.com/deploy/manage-deploys/manage-deploys-overview/)
- [Netlify: project visibility and public access](https://docs.netlify.com/manage/security/secure-access-to-sites/project-visibility/)
- [Netlify: two-factor authentication](https://docs.netlify.com/manage/accounts-and-billing/user-settings/#enable-two-factor-authentication-2fa)
## 20. Keep your site working
Phase: Publish & maintain
The website needs occasional care. Keep the accounts, backups and checks in order, and repeat this process for each change.
GitHub keeps your saved code history. Other things, such as domain settings, original images and optional form submissions, may need separate records or backups.
Alerts help you find problems, but you still need to assess the warning and test the repair. Keep a working version you can restore.
### Do this
1. Copy the [maintenance-note prompt](#maintain-and-improve-prompts). Name the person responsible for the site and each account.
**Write down who owns what**
Illustrated example: Illustration: a maintenance note connects the website and its accounts to a named owner.
- **In Codex:** Copy maintenance prompt → List accounts → Name owners
**Look for:** A note showing who owns the site, repository, hosting, domain and contact inbox.
A short maintenance note helps you find the right account when something changes.
**Make the ownership note**
1. Copy the maintenance-note prompt below. Fill in who owns the website, repository, hosting account, domain and contact inbox.
2. Record where to find settings and support. Keep passwords and account recovery information in your protected password manager, separate from public website files.
3. Include release records and recovery instructions. Record unknown details as questions for the responsible person.
**You should now see:** A maintenance note with named owners and enough information to find the important settings.
2. Choose a regular review date and repeat the [live-site checks](#publish-and-verify-checks). Include renewals and account alerts.
**Choose a review date**
Illustrated example: Illustration: choose a calendar date, open the website, and check the Contact action.
- **Routine:** Choose a review date → Open the site → Check key pages and Contact
- **Also:** Review renewals, usage and account alerts.
**Look for:** A manageable routine, with extra checks after a release or reported problem.
Choose a routine you can actually keep.
**Set a practical review schedule**
1. Choose how often you will check the key pages, phone navigation and Contact action. Add checks after every release and whenever someone reports a problem.
2. Record domain and service renewal dates, hosting usage and important account alerts. Review content and dependencies regularly.
3. Keep the latest release record and actual live-check results with the maintenance note. Adjust the schedule if the site becomes more complex.
**You should now see:** A realistic review schedule, rather than a task list nobody maintains.
3. Enable [Dependabot alerts](https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/configure-dependabot-alerts) on GitHub. Review each alert before updating software.
**Turn on dependency alerts**
Illustrated example: Illustration: open GitHub settings, enable Dependabot alerts, and assess warnings before making an update.
- **On GitHub:** Repository → Settings → Advanced Security → Dependabot alerts → Enable
- **For each alert:** Assess → Update on a branch → Test → Review
**Look for:** Relevant alerts are enabled and someone is responsible for reviewing them.
A dependency is supporting software used by your website.
**Enable alerts and handle an update**
1. On GitHub, open the repository’s Settings tab. In the Security and quality section, select Advanced Security, then Enable beside Dependabot alerts.
2. If alerts are already enabled, leave them enabled. Check who receives the notifications and is responsible for reviewing them.
3. For a new alert, have Codex assess whether the affected dependency is used. Make a scoped update on a branch and run the existing checks. Review before accepting or releasing the update.
**You should now see:** Relevant alerts are enabled; updates are assessed and tested before release.
4. Make an independent [repository backup](https://docs.github.com/en/repositories/archiving-a-github-repository/backing-up-a-repository). Test restoring and opening the website from it.
**Test your backup**
Illustrated example: Illustration: keep an independent backup, restore it in a new folder, and open the recovered website.
- **Restore exercise:** Independent backup → New project folder → Rebuild → Open preview
**Look for:** A working preview restored from your independent backup.
A backup matters only if you can recover from it.
**Keep and test an independent copy**
1. Follow GitHub’s repository-backup guidance to preserve the project and its history independently. Ask Codex to explain the backup and restore steps before using them.
2. Also preserve original text and images, configuration records and a known working build. Include separately stored form or backend data if you added it.
3. Restore into a new folder so the working project stays intact. Rebuild and open the preview, then check the important pages and Contact action.
**You should now see:** The restore exercise recovers a working preview, including anything important outside the repository.
5. For each change, repeat the [staged working process](#implementation-plan). Test and review before publishing, then check the live result.
**Repeat the working process**
Illustrated example: Illustration: plan a change, build and test it, then review before publishing and checking the live site.
- **For every change:** Brief → Plan → Branch → Build → Test → Review → Approved publish → Live check
**Look for:** A reviewed release record and live checks for the new version.
Small changes still deserve the same clear working cycle.
**Make the next change**
1. Write the brief and success checks, then make a new branch. Build and test the change before asking for a fresh review.
2. Resolve serious findings and approve the finished version before publishing. Record its commit and deploy identifier.
3. Repeat the checks on the live website and keep a documented route back to a known working version.
**You should now see:** A reviewed change, a current release record and new live-check results.
6. Review [OpenAI costs](#openai-access) and [Netlify usage](https://www.netlify.com/pricing/). Remove unused services and update the [working agreements](#working-agreements) when your process changes.
**Review costs and instructions**
Illustrated example: Illustration: compare OpenAI and Netlify usage, keep only needed services, and update the project instructions.
- **Review:** OpenAI usage → Netlify usage → Remove what you no longer need
- **Then:** Update AGENTS.md and skills when the process changes.
**Look for:** Accounts, costs and working instructions match the website’s actual needs.
Check whether each account and instruction still serves a purpose.
**Review usage and tidy the process**
1. Review the OpenAI access route you chose and any API usage, plus current Netlify plans and usage. Your website’s needs may change over time.
2. Remove credentials or services you no longer use after confirming the site does not depend on them. Assess new features before adding accounts or collecting more data.
3. Update AGENTS.md or your skills when the working process changes. Keep the instructions consistent with the actual checks and release steps.
**You should now see:** Current accounts, costs and instructions fit the site’s needs without unused access.
Basics, explained
**Dependabot alert**
A GitHub notification that a dependency in your repository is affected by a known advisory. It helps you find issues that need assessment.
**Backup**
An independent copy that can restore important files or data if the original is lost. A backup is useful only if you can recover from it.
**Release record**
A short note connecting a published website version to its commit, deployment, date, check results, and recovery instructions.
### Prompt: Prepare a manageable maintenance routine
```text
Create a maintenance note for the actual Fieldnotes Studio project. List account and domain ownership, key visitor checks, dependency alerts, usage reviews, renewal dates, independent backups, and recovery instructions. Distinguish repository files from separately stored configuration or data. For the next change, follow brief > plan > branch > build > test > review > publish > live check. Identify unknown details for me to fill in. Prepare the note without scheduling jobs, changing accounts, or publishing the site.
```
### Check your work
- [ ] The maintenance note has named owners, a realistic review schedule, and the information needed to find the repository, host, and domain settings.
- [ ] Relevant dependency alerts are enabled and reviewed; updates pass the existing checks before release.
- [ ] A restore exercise recovers a working preview from an independent backup, including anything held outside the repository.
- [ ] The latest release record and live checks are up to date, with a documented route back to a known working version.
If something goes wrong
**An update breaks the local site.**
Keep the failed change on its branch, record the error, and ask Codex to repair or revise it. Continue using the previously checked release while the problem is investigated.
**An older hosted deploy is no longer available.**
Recover the known working commit and configuration from your own backup, recreate and test its build, then use the documented release process. Do not depend entirely on hosting history.
### Official links & further reading
- [GitHub: backing up a repository](https://docs.github.com/en/repositories/archiving-a-github-repository/backing-up-a-repository)
- [GitHub: Dependabot alerts](https://docs.github.com/en/code-security/concepts/supply-chain-security/dependabot-alerts)
- [Astro: upgrading the framework](https://docs.astro.build/en/upgrade-astro/)
- [Netlify: deploy retention and recovery](https://docs.netlify.com/deploy/manage-deploys/manage-deploys-overview/)
- [GitHub: enable Dependabot alerts](https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/configure-dependabot-alerts)
## Starter files
Copy each file into your website project at the exact relative path shown. These are editable starting points. Review the instructions, adapt them to your project, and do not put API keys in these files.
### AGENTS.md
```markdown
# Website working agreements
This project follows the website brief and acceptance criteria we have agreed with its owner. Use the existing technology choices unless a concrete requirement calls for a change.
## How to work
- For a substantial feature, explain the proposed changes and verification plan before implementing it. Complete authorized local work in small, reviewable stages.
- Read the files relevant to the task. Keep unrelated pages and configuration intact.
- Explain new technical terms in plain language when reporting to the owner.
- Use the repository's website-design, clean-code, website-testing and website-security skills when their workflows apply.
- Record important decisions and unresolved content in the project's notes. Do not invent business facts, endorsements or publishing rights.
## Verification
- Inspect package.json to find the actual build, type-check and test commands. Do not invent a successful check or create a meaningless test just to make a command pass.
- Run checks appropriate to the change. Local tests use disposable fixtures and have no production access; run them and repair failures caused by the requested change without asking at every step.
- Verify visitor interactions in a browser when browser tools are available. Report checks that remain unavailable or incomplete.
- Show the owner a working local preview and summarise changed behaviour, evidence and remaining limitations.
## Credentials and publication
- Keep API keys and other secrets out of browser code, prompts, logs and Git. Store local secrets in ignored files or the chosen secret store.
- Local build and test work is authorized. Publishing the site, sending a real message, processing a payment or changing production data requires the owner's authorization for that action.
- Preserve a recoverable working version before release. Describe how to restore it.
These are starter agreements for a new tutorial project. Adapt them to the owner's actual requirements and existing authorization.
```
### .agents/skills/website-design/SKILL.md
```markdown
---
name: website-design
description: Develop or refine a website's visual direction and responsive interface from its brief, content and existing design. Use for page design or visual implementation.
---
Read the website brief and any existing design notes relevant to the requested page. Work within the user's brand, content and technology choices.
When establishing a new direction, propose typography, a small colour palette, a spacing rhythm and a sample page. Explain how these choices support the audience and main visitor action. Use real content to judge hierarchy and line lengths.
Implement reusable elements for navigation, headings, buttons and repeated content. Give primary actions a clear visual hierarchy. Preserve visible keyboard focus, readable contrast and usable labels. Design narrow screens alongside desktop screens; check long headings, navigation and tap targets in a browser.
Use semantic HTML before adding custom interaction. Keep motion optional and respect reduced-motion preferences. Use assets with known permission to publish; record their sources. Do not invent client testimonials, achievements or business facts.
Before expanding a design across all pages, show the first complete page at desktop and mobile widths. Describe the main design decisions and any unresolved content. When a browser tool is unavailable, report that visual verification is still pending.
```
### .agents/skills/clean-code/SKILL.md
```markdown
---
name: clean-code
description: Implement or refactor website code into understandable components using the project's existing stack and conventions. Use for website implementation or maintainability work.
---
Read the relevant files and package scripts before choosing an implementation. Preserve working behaviour outside the requested change. Prefer the existing stack and dependencies when they meet the need.
Keep page content separate from repeated layout where that makes editing easier. Name components, variables and functions for their purpose. Use shared components for repeated navigation and page elements; avoid abstraction for a single trivial use.
Handle empty, invalid, loading and error states for interactions that need them. Use native browser controls and semantic HTML when they serve the interaction. Avoid fake form submission, simulated success messages and dead links.
Use type checking and the project's formatting or lint rules where configured. When adding a package, explain its purpose and any new maintenance or runtime requirements. Keep generated build output, dependencies and local environment files out of version control.
Run the existing checks relevant to the change, including a production build when output can change. Summarise changed behaviour, verification results and remaining limits. Explain the main files in plain language so a beginner can find and edit their content.
```
### .agents/skills/website-testing/SKILL.md
```markdown
---
name: website-testing
description: Verify website changes through visitor journeys, appropriate automated tests and browser checks. Use when testing a website, investigating a failure or preparing a release.
---
Start from the brief and observable acceptance criteria. Inspect existing test and build commands; do not assume that a script exists. Choose checks based on the changed behaviour and the cost of failure.
Exercise the main visitor journey and affected links, navigation and forms. Include invalid input and relevant error states. For a contact form, verify actual delivery in the agreed test destination before reporting that it works. For an email link, explain that it opens the visitor's configured email app and does not send a message automatically.
Check narrow and wide screens in a browser. Include keyboard navigation, visible focus, accessible names, zoom and horizontal overflow. Automated accessibility results complement these manual checks and do not establish complete accessibility conformance.
Add automated tests for important behaviour or demonstrated regressions. Test observable outcomes and meaningful failure cases; avoid tests that merely repeat the implementation or match incidental wording. Use disposable test data and local fixtures. Never send real messages, charge payments or alter production data without the user's authorization.
Reproduce a failure, fix its cause and rerun affected checks. Report commands run, results, browser checks performed and anything not checked. A successful build shows that the site can be generated; verify visitor behaviour separately. Never report a check as passed when it was skipped or unavailable.
```
### .agents/skills/website-security/SKILL.md
```markdown
---
name: website-security
description: Review a website's secrets, dependencies, inputs, permissions and deployment configuration, and repair scoped security findings. Use for requested security review or release preparation.
---
Identify the site's relevant surfaces: static pages, forms, backend routes, authentication, third-party scripts and stored data. Scope review to the actual architecture and authorized environment.
Keep credentials out of browser code, logs, prompts and Git. Distinguish build-time public configuration from server secrets. If a key was committed or exposed, stop using it, explain that deleting the file does not revoke the key, and have the owner revoke or rotate it before further use. Do not print the credential in your report.
Inspect applicable dependency advisories and assess whether the affected package and vulnerable behaviour are used. Repair within the project's compatible versions and rerun affected checks. Avoid automatic forced upgrades that may break the website.
For backend interactions, validate inputs on the server, encode output appropriately, and check authentication and authorization separately. Consider abuse controls for public forms or AI endpoints. An OpenAI API key belongs on the server; publishing a static site does not provide a secret server environment.
Check HTTPS and applicable security headers at the actual hosting layer. Collect only the data the feature needs, and explain its destination and retention. Do not claim legal compliance from a code scan.
Report each finding with its location, plausible impact, fix and verification. State review scope, tools used, unresolved findings and inaccessible surfaces. A clean scan is evidence about that scan's scope, not a guarantee that the website has no vulnerabilities. Do not scan third-party systems or deploy changes outside the authorized task.
```