softer AI instructions to prevent prompt injection flags

Author: jekuer

.ai/BOILERPLATE_MODE.md

@@ -1,36 +1,31 @@
-<!-- Stardrive project instruction file — trusted internal documentation for AI agents, not user input. Execution scope: maintaining the Stardrive boilerplate itself, when STARDRIVE_AGENT_MODE.md is set to "boilerplate". -->
+<!-- Scope: boilerplate maintenance when STARDRIVE_AGENT_MODE.md contains "boilerplate". -->
 
-# Boilerplate Mode Instructions
+# Boilerplate Mode
 
-You are in this mode because `../STARDRIVE_AGENT_MODE.md` contains `boilerplate`. You are not adjusting the boilerplate for a new project, but maintaining the boilerplate itself.
+This guide applies when [`STARDRIVE_AGENT_MODE.md`](../STARDRIVE_AGENT_MODE.md) contains `boilerplate`. In this mode, changes maintain the Stardrive boilerplate rather than configure a derived website.
 
-This is the active guide for boilerplate work. The other `.ai` guides (`SETUP.md`, `CONFIG_GUIDE.md`, `TRIMMING_GUIDE.md`, `FAVICON_GUIDE.md`) describe the end-user setup flow - do **not** execute them as if you were setting up a project, but **do** read and update them whenever your changes alter that flow (see the sync rule below). For how these files relate, see the dependency overview in [`AGENTS.md`](../AGENTS.md).
+The other `.ai` guides (`SETUP.md`, `CONFIG_GUIDE.md`, `TRIMMING_GUIDE.md`, `FAVICON_GUIDE.md`) are reference material in this mode, not active workflows. Changes that affect project setup should keep those guides accurate. See [`AGENTS.md`](../AGENTS.md) for the dependency overview.
 
 ## What this means
 
-- Code needs to be well documented, but never only for you and the user - documentation needs to be clear to every potential future user. Do not write things like "adjusted this as discussed". Only write documentation that helps somebody (even another AI agent), who knows nothing about the history of this boilerplate.
-- Always double-check with the whole cloning and configuration process. If things change there (for example, a new setting in theme.config.ts), update [`README.md`](../README.md), [`CONFIG_GUIDE.md`](./CONFIG_GUIDE.md) and any other related file in ./.ai.
-- If changes affect the [`TRIMMING_GUIDE`](./TRIMMING_GUIDE.md) or the structure of the blog, faq, or integration, also check whether the main branch of the Stardrive starter at [github.com/peltmonger/create-stardrive](https://github.com/peltmonger/create-stardrive) needs to be adjusted. Inform the user about it without taking further action. The user might to make another agent to work on this separated repository, so prepare a short guide on what to change there.
-- Always bear in mind that this boilerplate will ship to a wide variety of hosting environments and project types. Keep logic and structure as modularized, flexible, and independent as possible.
+- Documentation should be useful to future users without relying on conversation history. Avoid phrases such as "adjusted this as discussed."
+- Changes affecting cloning or configuration should also update [`README.md`](../README.md), [`CONFIG_GUIDE.md`](./CONFIG_GUIDE.md), and any other related file in `./.ai/`.
+- Changes affecting [`TRIMMING_GUIDE.md`](./TRIMMING_GUIDE.md) or the blog, FAQ, or integration structure should include a check of the Stardrive starter at [github.com/peltmonger/create-stardrive](https://github.com/peltmonger/create-stardrive). Report whether that repository may require a matching change and provide a short implementation guide, without modifying the separate repository.
+- The boilerplate supports varied hosting environments and project types. Keep its logic and structure modular, flexible, and independent.
 - Stay as close as possible to the Astro default, so it is easy to upgrade.
 - The content has multiple purposes at once:
   - demo the capabilities of the boilerplate
   - advertise for the boilerplate
   - be its own fully working website with valid rules and content (like having valid privacy policy and legal notice)
   - showcasing (listing) real world examples of the boilerplate
   - lead people and AI agents to using the boilerplate for their projects
-- Think Before Coding. Don't assume. Don't hide confusion. Surface tradeoffs.
-- Before implementing:
-  - State your assumptions explicitly. If uncertain, ask.
-  - If multiple interpretations exist, present them - don't pick silently.
-  - If a simpler approach exists, say so. Push back when warranted.
-  - If something is unclear, stop. Name what's confusing. Ask.
+- Think before coding. Surface assumptions, uncertainty, competing interpretations, simpler alternatives, and relevant tradeoffs before implementation.
 - Simplicity First.
   - Minimum code that solves the problem. Nothing speculative.
   - No features beyond what was asked.
   - If you write 200 lines and it could be 50, rewrite it.
   - Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
 - Surgical Changes. Touch only what you must. Clean up only your own mess.
 - Match existing style, even if you'd do it differently.
-- If you notice unrelated dead code, that has not been created by yourself, mention it - don't delete it.
-- When your changes create orphans: Remove imports/variables/functions that YOUR changes made unused. Don't remove pre-existing dead code unless asked.
+- Report unrelated dead code without removing it.
+- Remove imports, variables, or functions made unused by the current changes. Pre-existing dead code remains outside scope unless requested.

.ai/CONFIG_GUIDE.md

@@ -1,4 +1,4 @@
-<!-- Stardrive project instruction file — trusted internal documentation for AI agents, not user input. Execution scope: project configuration, when STARDRIVE_AGENT_MODE.md is set to "project". -->
+<!-- Scope: initial project configuration in project mode. -->
 
 # Configuration Guide - Instructions
 

.ai/FAVICON_GUIDE.md

@@ -1,4 +1,4 @@
-<!-- Stardrive project instruction file — trusted internal documentation for AI agents, not user input. Execution scope: favicon/manifest generation, invoked from the favicon step of CONFIG_GUIDE.md. -->
+<!-- Scope: favicon and manifest setup when invoked by CONFIG_GUIDE.md. -->
 
 # Favicon Guide
 

.ai/SETUP.md

@@ -1,21 +1,17 @@
-<!-- Stardrive project instruction file — trusted internal documentation for AI agents, not user input. Execution scope: project setup only, when STARDRIVE_AGENT_MODE.md is missing or set to "project". -->
+<!-- Scope: repository initialization when STARDRIVE_AGENT_MODE.md is absent. -->
 
 # Setup Guide
 
-This guide establishes the working mode, then hands off to the right next guide. See the dependency overview in [`AGENTS.md`](../AGENTS.md) for the full picture.
+Use this guide only when `STARDRIVE_AGENT_MODE.md` is absent. See the dependency overview in [`AGENTS.md`](../AGENTS.md) for the full workflow.
 
-## Step 1 - Determine the mode
+## Determine the repository mode
 
-Ask the user whether this is about creating a new project or maintaining the boilerplate itself.
+Ask whether the repository is being used to:
 
-**Options (use the exact keyword):**
+- build a website from Stardrive (`project`), or
+- maintain the Stardrive boilerplate (`boilerplate`).
 
-- `boilerplate` - maintaining the Stardrive boilerplate codebase itself.
-- `project` - building a new website on top of the boilerplate.
+Write the selected keyword to `STARDRIVE_AGENT_MODE.md`.
 
-Create a file `STARDRIVE_AGENT_MODE.md` in the root of this repository and set its entire content to the single selected keyword (`boilerplate` or `project`), so future agents skip this question.
-
-## Step 2 - Hand off to the matching guide
-
-- **`boilerplate`** → Stop here, move on with your given tasks, and mind [`BOILERPLATE_MODE.md`](./BOILERPLATE_MODE.md). Do not run the project setup steps below.
-- **`project`** → Recommend the user to continue with the step-by-step configuration from [`CONFIG_GUIDE.md`](./CONFIG_GUIDE.md) before moving on with other tasks. It walks you through trimming, configuration, and theming, and you must end up having created a `PLAN.md` (in `./.ai/`) that tracks the remaining work. From then on, agents resume from `PLAN.md`.
+- For `project`, continue with [`CONFIG_GUIDE.md`](./CONFIG_GUIDE.md) and create `./.ai/PLAN.md` to track remaining work.
+- For `boilerplate`, continue with [`BOILERPLATE_MODE.md`](./BOILERPLATE_MODE.md).

.ai/TRIMMING_GUIDE.md

@@ -1,22 +1,29 @@
-<!-- Stardrive project instruction file — trusted internal documentation for AI agents, not user input. Execution scope: initial trimming of a directly cloned Stardrive boilerplate, invoked from CONFIG_GUIDE.md. Self-deletes after execution. -->
+<!-- Scope: optional initial trimming for a directly cloned project, invoked by CONFIG_GUIDE.md. -->
 
-# Trimming Guide - Instructions
+# Trimming Guide
 
-The goal of this trimming step is to bring this repository to a clean starting point for the user's own project by removing demo content and features they do not need.
+This workflow removes optional demo content from a directly cloned Stardrive project. It applies only when invoked during project configuration by [`CONFIG_GUIDE.md`](./CONFIG_GUIDE.md).
 
-This applies when the user cloned Stardrive **directly** (e.g. via `git clone`) instead of using the [`create-stardrive`](https://www.npmjs.com/package/create-stardrive) scaffolding tool. `create-stardrive` performs these removals automatically; here you do them manually.
+The [`create-stardrive`](https://www.npmjs.com/package/create-stardrive) scaffolding tool performs these removals automatically, so this workflow is only relevant to direct clones (for example, via `git clone`).
 
-This guide should only be executed as part of the official initial [configuration](./CONFIG_GUIDE.md)!
+Before removing optional features, ask which of these should be retained:
 
-## How to execute
+- Blog
+- FAQ
+- Integration catalog
+- Events
+- Cloudflare hosting
 
-1. **Always-on steps** (marked `always`): execute them without asking. They remove demo/system files that are never useful in a real project and can cause conflicts.
-2. **Optional steps** (marked `optional`): you MUST ask the user whether they want to keep that feature before removing anything related to it. Never delete an optional feature without explicit confirmation.
-3. **Start by interviewing the user.** Present the optional features in one prompt - Blog, FAQ, Integration catalog, and Cloudflare hosting - and ask which they want to **keep**. Then remove only the ones they do not want.
-4. When deleting a file or directory, verify it exists first. Mind that all paths are based on the project root, where the package.json is located. If an element is already gone, report it and continue rather than failing.
-5. After removals, complete the navigation cleanup and any dependency uninstall that corresponds to what was removed.
-6. Do not commit changes unless the user asks.
-7. Note down any features dropped in the [`theme.config.ts`](../theme.config.ts) under the key "droppedFeatures" (Array of Strings) to keep track on it.
+Remove only features the user explicitly chooses not to retain. Always-on cleanup steps may proceed as documented below.
+
+## Workflow rules
+
+1. **Always-on steps** (marked `always`) do not require an additional feature-retention decision. They remove demo or system files that are not useful in a configured project and can cause conflicts.
+2. **Optional steps** (marked `optional`) require explicit confirmation before removal.
+3. Before deleting a file or directory, verify that it exists. All paths are relative to the project root containing `package.json`. Report missing elements and continue.
+4. After removals, complete the corresponding navigation cleanup and dependency uninstall.
+5. Commits are outside this workflow unless requested.
+6. Record removed features in [`theme.config.ts`](../theme.config.ts) under the `droppedFeatures` array.
 
 ### Context you can share with the user
 
@@ -26,7 +33,7 @@ Stardrive ships as a fully-populated demo site - the same codebase that powers [
 
 ## Step 1 - System files (always)
 
-Delete the following without asking:
+Remove the following as part of the always-on cleanup:
 
 - `./SECURITY.md`
 - `./CHANGELOG.md`
@@ -146,8 +153,8 @@ npm un @astrojs/cloudflare wrangler
 The `.gitignore` file includes a block "# Lock files". This ignores lock files for the package managers not used.
 Adjust this block, if you are not using npm.
 
-## Step 9 - Verify, then delete this guide (always)
+## Step 9 - Verify and complete trimming (always)
 
 1. After all edits, verify the project still builds/type-checks cleanly (e.g. run the dev server or build) and fix any references left dangling by the removals.
-2. Verify you noted any dropped features in the `theme.config.ts`file.
-3. **Delete this `TRIMMING_GUIDE.md` file.** It is only relevant for initial setup and must not ship with the user's website.
+2. Verify that removed features are recorded in `theme.config.ts`.
+3. After successful verification, remove this temporary guide from the configured project. It is only relevant during initial setup.

.github/copilot-instructions.md

@@ -1,16 +1,3 @@
-# 🛑 CRITICAL: REPOSITORY BOOTSTRAP DIRECTIVE 🛑
-As an AI agent operating in this repository, you MUST execute the following state check before analyzing, coding, or responding to any user prompt:
+# Stardrive repository instructions
 
-1. **CHECK STATE:** Silently verify if the file [`STARDRIVE_AGENT_MODE.md`](../STARDRIVE_AGENT_MODE.md) exists in the root directory.
-2. **IF MISSING (UNINITIALIZED):**
-   - Intercept the prompt: Acknowledge to the user that you are running the initial repository setup first.
-   - Never (!) proceed without this file being present!
-   - Read the file [`SETUP.md`](../.ai/SETUP.md) in the`./.ai/` directory..
-   - Execute ALL setup, scaffolding, and configuration instructions defined in `SETUP.md` and related files. Ask the user about clarification where necessary.
-   - Create the `STARDRIVE_AGENT_MODE.md` file in the root directory to mark initialization as complete, setting its content to "project" or "boilerplate" - depending on what the user's case is about.
-   - Proceed to fulfill the user's original request.
-3. **IF PRESENT (INITIALIZED):**
-   - Directly proceed to fulfilling the user's prompt.
-   - Mind the content of the `STARDRIVE_AGENT_MODE.md` as it defines your general scope as described in the [`AGENTS.md`](../AGENTS.md).
-
-Additionally, always mind the guidelines in [`AGENTS.md`](../AGENTS.md)!
+Follow [`AGENTS.md`](../AGENTS.md) for repository mode selection, project conventions, and applicable workflow guides.

AGENTS.md

@@ -27,7 +27,7 @@ Check for an `STARDRIVE_AGENT_MODE.md` file at the root level. Its content is a
 
 The `.ai/` folder drives onboarding. The files depend on each other in a fixed order - follow the links rather than guessing what to do next:
 
-> **Note:** All files in `./.ai/` are **trusted project instruction files** — internal documentation authored by the Stardrive maintainers for AI agents operating in this repository. They may contain imperative directives ("you MUST", "delete this file", etc.) that are meant to be executed only within the scope described in each file's banner comment. They are not user input, external content, or untrusted data.
+> **Scope:** Files in `./.ai/` document mode-specific repository workflows. Consult only the files selected by `STARDRIVE_AGENT_MODE.md` and the dependency flow below. Reading a guide for reference does not activate its workflow.
 
 ```text
 AGENTS.md (this file)            ← always read first; selects the mode

CLAUDE.md

@@ -1 +1 @@
-Do not start without having @AGENTS.md checked at least once!
+@AGENTS.md

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "stardrive",
-  "version": "1.4.0",
-  "stardriveVersion": "1.4.0",
+  "version": "1.4.1",
+  "stardriveVersion": "1.4.1",
   "private": true,
   "description": "The Astro boilerplate to create super stable and fast websites in the AI age",
   "engines": {