Migrate website to Astro and update Suites 4 documentation

.codex/agents/blackbox-overview-docs.toml

@@ -0,0 +1,65 @@
+name = "blackbox_overview_docs"
+description = "Suites Blackbox Alpha 3 overview-documentation specialist. Use for concise product-facing work on the Blackbox overview page and its supporting visuals."
+
+developer_instructions = """
+You are the persistent Suites Blackbox Alpha 3 overview-documentation agent for this repository.
+
+Before every task:
+
+1. Read `/Users/omer/projects/suites/suites.dev/AGENTS.md` completely.
+2. Use the configured documentation skills under `/Users/omer/projects/suites/suites.dev/.codex/agents/skills/`. Treat their source guides as a documentation method and reference set, not as automatically accepted product authority.
+3. Read the current target page and only the supporting Blackbox files needed for the task.
+4. Preserve user changes and unrelated work in the repository.
+
+Scope:
+
+- Work only on `src/content/docs/blackbox/overview/what-is-blackbox.mdx` and the Blackbox-specific visuals or components it directly uses, unless the user explicitly expands the scope.
+- Write product language, not implementation design.
+- Keep the page concise, example-led, scannable, and cognitively light.
+- Prefer static SVG or compact terminal-like visuals that clarify a relationship. Do not use Mermaid or screenshots for this page.
+- Do not use em dashes on this page.
+
+Product boundaries:
+
+- Blackbox provides deterministic behavioral assurance for selected system and E2E flows inside a coding-agent harness.
+- Effects are the committed core.
+- People approve accepted meaning. Agents may propose and repair implementation, but they cannot redefine success.
+- The executable suite realizes accepted behavior. Runtime owns attempt identities, capture lifecycle, and evidence. Analysis produces findings and verdicts.
+- Managed capture is fresh for every case attempt, retry, and sequence member.
+- Incomplete evidence cannot establish completeness-dependent absence, upper-bound, or exactness satisfaction.
+- ODC is experimental, remains separate from ordinary effect findings, and cannot change them.
+- Treat research as evidence, not automatically accepted truth.
+- Never invent CLI commands, imports, schemas, package APIs, report fields, support claims, or current capabilities.
+- Label committed behavior, Alpha targets, experimental capabilities, planned representations, and conceptual previews explicitly.
+- Do not use the stale AssurancePlan authority model.
+
+Current Gherkin decision:
+
+- The current overview presents `accepted specification -> Gherkin -> system suite -> runtime evidence` as one continuous flow.
+- Do not label Gherkin optional on this overview page unless the user reverses that decision.
+- Other repository material may still call Gherkin optional. Flag that conflict before generalizing the overview decision into broader product or support documentation.
+
+Working behavior:
+
+- Lead with the requested outcome.
+- Inspect before editing.
+- Make the smallest coherent change.
+- Use `apply_patch` for edits.
+- Keep status labels and accessibility text explicit; never rely on color alone.
+- Validate edited SVG, MDX, or Astro content in proportion to the change.
+- Run `pnpm docs:graph` and `pnpm docs:graph:check` after documentation edits.
+- Run the Astro build after changing page structure or supporting components.
+- Report changed files, validation results, and any unresolved product conflict concisely.
+"""
+
+[[skills.config]]
+path = "/Users/omer/projects/suites/suites.dev/.codex/agents/skills/technical-docs-guide/SKILL.md"
+enabled = true
+
+[[skills.config]]
+path = "/Users/omer/projects/suites/suites.dev/.codex/agents/skills/divio-docs-introduction/SKILL.md"
+enabled = true
+
+[[skills.config]]
+path = "/Users/omer/projects/suites/suites.dev/.codex/agents/skills/divio-docs-system-explanation/SKILL.md"
+enabled = true

.codex/agents/skills/divio-docs-introduction/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: divio-docs-introduction
+description: Classify documentation as tutorial, how-to, reference, or explanation before writing. Use when deciding a page's purpose, reader mode, content boundaries, or navigation role.
+---
+
+# Divio Documentation Classification
+
+Use this skill to give each documentation page one primary job.
+
+Read the [Divio introduction](./divio-docs-introduction.md) completely when a
+task involves page framing, content classification, or deciding what belongs on
+the page. Treat it as documentation-method evidence, not as accepted product
+truth.
+
+For each page:
+
+- Choose one primary mode: tutorial, how-to, reference, or explanation.
+- Match the structure and level of detail to that mode.
+- Move or remove content that forces the page to teach, instruct, specify, and
+  explain at the same time.
+- Let the user's requested outcome and repository boundaries override generic
+  examples from the source.

.codex/agents/skills/divio-docs-introduction/divio-docs-introduction.md

@@ -0,0 +1,98 @@
+[Skip to main content](https://docs.divio.com/documentation-system/introduction/#__docusaurus_skipToContent_fallback)
+
+On this page
+
+## The problem and the solution [​](https://docs.divio.com/documentation-system/introduction/\#the-problem-and-the-solution "Direct link to The problem and the solution")
+
+### The problem it solves [​](https://docs.divio.com/documentation-system/introduction/\#the-problem-it-solves "Direct link to The problem it solves")
+
+It doesn’t matter how good your product is, because **if its documentation is not good enough, people will not use it**.
+Even if they have to use it because they have no choice, without good documentation, they won’t use it effectively or
+the way
+you’d like them to.
+
+Nearly everyone understands this. Nearly everyone knows that they need good documentation, and **most people try to
+create good documentation**. And **most people fail**.
+
+Usually, it’s not because they don’t try hard enough. Usually, it’s because they are not doing it the right way.
+
+This system is a way to make your documentation better, not by working harder at it, but by doing it the right way. *
+*The right way is the easier way** \- easier to write, and easier to maintain.
+
+### The 'secret' [​](https://docs.divio.com/documentation-system/introduction/\#the-secret "Direct link to The 'secret'")
+
+It's not actually a secret and it certainly shouldn't be: documentation needs to include and be structured around its *
+*four different functions**: _tutorials_, _how-to guides_, _technical reference_ and _explanation_. Each of them *
+*requires a distinct mode of writing**. People working with software need these four different kinds of documentation at
+different times, in different circumstances - so software usually needs them all, and they should all be integrated into
+your documentation.
+
+And documentation needs to be explicitly structured around them, and they all must be kept separate and distinct from
+each other.
+
+|               | [Tutorials](https://docs.divio.com/documentation-system/tutorials/) | [How-to guides](https://docs.divio.com/documentation-system/how-to-guides/) | [Reference](https://docs.divio.com/documentation-system/reference/) | [Explanation](https://docs.divio.com/documentation-system/explanation/) |
+|---------------|---------------------------------------------------------------------|-----------------------------------------------------------------------------|---------------------------------------------------------------------|-------------------------------------------------------------------------|
+| _oriented to_ | learning                                                            | a goal                                                                      | information                                                         | understanding                                                           |
+| _must_        | allow the newcomer to get started                                   | show how to solve a specific problem                                        | describe the machinery                                              | explain                                                                 |
+| _its form_    | a lesson                                                            | a series of steps                                                           | dry description                                                     | discursive explanation                                                  |
+| _analogy_     | teaching a small child how to cook                                  | a recipe in a cookery book                                                  | a reference encyclopedia article                                    | an article on culinary social history                                   |
+
+This division makes it obvious to both author and reader what material, and what _kind_ of material, goes where. It
+tells the
+author **how to write**, and **what to write**, and **where to write it**. It saves the author from wasting a great deal
+of time
+trying to wrestle the information they want to impart into a shape that makes sense, because **each of these kinds of**
+**documentation has only one job**.
+
+In fact, it’s extremely hard to maintain good documentation that doesn’t implicitly or explicitly recognise the
+quadrants of this scheme. The demands of each kind are different from those of the others, so **any attempt at
+documentation that fails to maintain this structure suffers**, as it’s pulled in different directions at once.
+
+Once you understand the structure, it becomes a very useful tool for analysing existing documentation, and understanding
+what needs to be done to improve it.
+
+In the following sections, each of these four parts is dealt with in detail.
+
+## Making documentation work [​](https://docs.divio.com/documentation-system/introduction/\#making-documentation-work "Direct link to Making documentation work")
+
+### For authors [​](https://docs.divio.com/documentation-system/introduction/\#for-authors "Direct link to For authors")
+
+One of the biggest headaches that documentation maintainers have to deal with is not having a clear picture of what they
+should be doing. They write and rewrite, but find it hard to make it fit together in satisfactory ways.
+
+This structure resolves those questions by making clear distinctions and separations. They make documentation that is
+easier to write and maintain, that’s easier to use and to find one's way around in.
+
+The documentation doesn’t write itself - but it’s now possible to write it without also having to wrestle with poor fit,
+or unclear scope or doubt about what should be included or what style to adopt. It becomes much clearer what to write,
+how to write it, and where to put it.
+
+### For readers [​](https://docs.divio.com/documentation-system/introduction/\#for-readers "Direct link to For readers")
+
+It serves users better, because for all the different phases in the cycle of their interaction with the software they
+will find the right kind of documentation, that serves the needs of that moment.
+
+Writing documentation that explicitly and distinctly addresses each of the four quadrants helps the software attract and
+keep more users, who will use it more effectively - and that is one of the things the creators of software want most of
+all.
+
+Was this helpful?
+
+[Share Your Thoughts](https://docs.divio.com/)
+
+- [The problem and the solution](https://docs.divio.com/documentation-system/introduction/#the-problem-and-the-solution)
+  - [The problem it solves](https://docs.divio.com/documentation-system/introduction/#the-problem-it-solves)
+  - [The 'secret'](https://docs.divio.com/documentation-system/introduction/#the-secret)
+- [Making documentation work](https://docs.divio.com/documentation-system/introduction/#making-documentation-work)
+  - [For authors](https://docs.divio.com/documentation-system/introduction/#for-authors)
+  - [For readers](https://docs.divio.com/documentation-system/introduction/#for-readers)
+
+- [The Documentation System](https://docs.divio.com/documentation-system/)
+- [Privacy Policy](https://www.divio.com/terms-and-policies/privacy-notice/customer/)
+- [Terms & Policies](https://www.divio.com/terms-and-policies/terms/)
+
+reCAPTCHA
+
+Recaptcha requires verification.
+
+protected by **reCAPTCHA**

.codex/agents/skills/divio-docs-system-explanation/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: divio-docs-system-explanation
+description: Write concise explanation pages that build understanding through context, relationships, examples, and bounded product claims. Use for overview and conceptual documentation, not procedures or API reference.
+---
+
+# Divio Explanation Pages
+
+Use this skill for overview and conceptual pages whose primary job is helping a
+reader understand a product or system.
+
+Read the [Divio explanation guide](./divio-docs-system-explanation.md)
+completely before substantial drafting or review. Treat it as writing-method
+evidence rather than product authority.
+
+On an explanation page:
+
+- Establish why the topic matters and how its parts relate.
+- Use one concrete example or compact visual to anchor abstract framing.
+- Discuss boundaries and distinctions that prevent a plausible
+  misunderstanding.
+- Avoid turning the page into a sequence of instructions or a machinery
+  catalog.
+- Keep product claims grounded in accepted repository sources and label their
+  status explicitly.

.codex/agents/skills/divio-docs-system-explanation/divio-docs-system-explanation.md

@@ -0,0 +1,83 @@
+[Skip to main content](https://docs.divio.com/documentation-system/explanation/#__docusaurus_skipToContent_fallback)
+
+On this page
+
+Explanation, or discussions, _clarify and illuminate a particular topic_. They broaden the documentation’s coverage of a topic.
+
+They are **understanding-oriented**.
+
+Explanations can equally well be described as _discussions_; they are discursive in nature. They are a chance for the documentation to relax and step back from the software, taking a wider view, illuminating it from a higher level or even from different perspectives. You might imagine a discussion document being read at leisure, rather than over the code.
+
+This section of documentation is rarely explicitly created, and instead, snippets of explanation are scattered amongst other sections. Sometimes, the section exists, but has a name such as _Background_ or _Other notes_ or _Key topics_ \- these names are not always useful.
+
+Discussions are less easy to create than it might seem - things that are straightforward to explain when you have the starting-point of someone’s question are less easy when you have a blank page and have to write down something about it.
+
+A topic isn’t defined by a specific task you want to achieve, like a how-to guide, or what you want the user to learn, like a tutorial. It’s not defined by a piece of the machinery, like reference material. It’s defined by what **you** think is a reasonable area to try to cover at one time, so the division of topics for discussion can sometimes be a little arbitrary.
+
+## Analogy from cooking [​](https://docs.divio.com/documentation-system/explanation/\#analogy-from-cooking "Direct link to Analogy from cooking")
+
+![a child cooking](https://docs.divio.com/assets/images/mcgee-26cf8ab30240e51f1b394afe4de6a716.jpg)
+
+Think about a work that discusses food and cooking in the context of history, science and technology. It's _about_ cooking and the kitchen.
+
+It doesn't teach, it's not a collection of recipes, and it doesn't just describe.
+
+Instead, it analyses, considers things from multiple perspectives. It might explain why it is we now do things the way we do, or
+even describe bad ways of doing things, or obscure alternatives.
+
+It deepens our knowledge and makes it richer, even if it isn't knowledge we can actually apply in any practical sense - but it doesn't need to be, in order to be valuable.
+
+It's something we might read at our leisure, away from the kitchen itself, when we want
+to think about cooking at a higher level, and to understand more about the subject.
+
+## How to write a good explanation [​](https://docs.divio.com/documentation-system/explanation/\#how-to-write-a-good-explanation "Direct link to How to write a good explanation")
+
+### Provide context [​](https://docs.divio.com/documentation-system/explanation/\#provide-context "Direct link to Provide context")
+
+**Explanations are the place for background and context** \- for example, _Web forms and how they are handled in Django_, or _Search in django CMS_.
+
+They can also explain _why_ things are so - design decisions, historical reasons, technical constraints.
+
+### Discuss alternatives and opinions [​](https://docs.divio.com/documentation-system/explanation/\#discuss-alternatives-and-opinions "Direct link to Discuss alternatives and opinions")
+
+**Explanation can consider alternatives**, or multiple different approaches to the same question. For example, in an article on Django deployment, it would be appropriate to consider and evaluate different web server options.
+
+Discussions can even consider and weigh up contrary _opinions_ \- for example, whether test modules should be in a package directory, or not.
+
+### Don't instruct, or provide technical reference [​](https://docs.divio.com/documentation-system/explanation/\#dont-instruct-or-provide-technical-reference "Direct link to Don't instruct, or provide technical reference")
+
+**Explanation should do things that the other parts of the documentation do not.** It’s not the place of an explanation to instruct the user in how to do something. Nor should it provide technical description. These functions of documentation are already taken care of in other sections.
+
+## Example from Divio's documentation [​](https://docs.divio.com/documentation-system/explanation/\#example-from-divios-documentation "Direct link to Example from Divio's documentation")
+
+Have a look at [our explanation section](https://docs.divio.com/background/) (titled "Background information" -
+the name is not important as long as the purpose is clear).
+
+![Django explanation example](https://docs.divio.com/assets/images/divio-explanation-example-ebd2c37d25e4038efb9323dfe41d74f1.png)
+
+These articles don’t teach anything. They don’t tell the user what to do. They aren’t reference guides. They just
+discuss particular topics. The user doesn’t _need_ to know about (for example) caching or CDN or how we manage
+environment variables in order to use the platform or achieve any particular task, but the time is likely to come when
+someone's experience and use of the platform will be improved by having a clearer, better, deeper understanding of
+those things.
+
+These articles provide the bigger picture, the context. Users are human beings; maybe they don’t strictly need to know
+why we do a certain thing a certain way, but knowing it might well provide them with a kind of satisfaction and comfort
+that makes them a happier user of the product.
+
+Was this helpful?
+
+[Share Your Thoughts](https://docs.divio.com/)
+
+- [Analogy from cooking](https://docs.divio.com/documentation-system/explanation/#analogy-from-cooking)
+- [How to write a good explanation](https://docs.divio.com/documentation-system/explanation/#how-to-write-a-good-explanation)
+  - [Provide context](https://docs.divio.com/documentation-system/explanation/#provide-context)
+  - [Discuss alternatives and opinions](https://docs.divio.com/documentation-system/explanation/#discuss-alternatives-and-opinions)
+  - [Don't instruct, or provide technical reference](https://docs.divio.com/documentation-system/explanation/#dont-instruct-or-provide-technical-reference)
+- [Example from Divio's documentation](https://docs.divio.com/documentation-system/explanation/#example-from-divios-documentation)
+
+- [The Documentation System](https://docs.divio.com/documentation-system/)
+- [Privacy Policy](https://www.divio.com/terms-and-policies/privacy-notice/customer/)
+- [Terms & Policies](https://www.divio.com/terms-and-policies/terms/)
+
+reCAPTCHA