Reorganize specifications.

.gemini/GEMINI.md

@@ -1,92 +1,3 @@
 # Gemini Code Assistant Context
 
-This document provides context for the Gemini Code Assistant to understand the `genui` project.
-
-## Project Overview
-
-This is a monorepo for a Generative UI SDK (`genui`). The SDK allows developers to add interactive, dynamic, and graphical UI to their applications, generated by a Large Language Model (LLM). Instead of rendering static text responses from an LLM, this SDK allows the LLM to compose UIs from a developer-provided widget catalog.
-
-The project is structured as a monorepo containing several Dart and Flutter packages, along with example applications.
-
-### Key Packages
-
-| Package                              | Description                                                             |
-| ------------------------------------ | ----------------------------------------------------------------------- |
-| `packages/genui`                     | The core framework for employing Generative UI.                         |
-| `packages/genui_a2ui`                | Integration with the A2UI Streaming UI Protocol.                        |
-| `packages/genui_firebase_ai`         | Firebase AI integration for `genui`.                                    |
-| `packages/genui_google_generative_ai`| Integration with Google Cloud Generative Language API.                  |
-| `packages/json_schema_builder`       | A Dart JSON Schema package with validation, used by the core framework. |
-
-### Example Applications
-
-The `examples` directory contains sample applications demonstrating the usage of the `genui` SDK.
-
-| Example           | Description                                                                                                                                                                                                                                                       |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `simple_chat`     | A minimal example of a conversational chat application. It demonstrates the fundamental concepts of `genui`, such as initializing the `GenUiConversation`, sending user messages, and rendering the AI-generated UI surfaces using the default core widget catalog. |
-| `travel_app`      | A more advanced example of a travel planning assistant. It showcases dynamic UI generation, the use of a custom, domain-specific widget catalog, and how user interactions with the UI can be fed back to the AI to refine the conversation.                      |
-| `catalog_gallery` | A simple application that displays the widgets available in the catalog. It's a useful tool for developers to visualize the components that the AI can use to build UIs.                                                                                          |
-| `verdure`         | A full-stack example (Flutter client + Python server) of a landscape design agent using the A2A protocol.                                                                                                                                                         |
-| `custom_backend`  | Demonstrates how a custom backend can interact with `genui`.                                                                                                                                                                                                      |
-
-The `simple_chat` and `travel_app` examples are good starting points for understanding the library's capabilities.
-
-## Implementation Details
-
-For a deeper understanding of the project's architecture and data flow, refer to the following documents:
-
-- **`packages/genui/DESIGN.md`**: Provides a comprehensive overview of the core `genui` package's architecture, purpose, and implementation.
-
-## Building and Running
-
-The project uses standard `flutter` and `dart` commands. A comprehensive script is provided to automate fixes, formatting, analysis, and testing.
-
-### Key Commands
-
-- **Run all checks and tests:**
-
-  ```bash
-  ./tool/run_all_tests_and_fixes.sh
-  ```
-
-  This script wraps the `test_and_fix` Dart tool (`tool/test_and_fix`) to run `dart fix`, `dart format`, `fix_copyright` (in `tool/fix_copyright`), `flutter test`, and `flutter analyze` for all packages and examples in the repository. It is used by developers before comitting code. It takes a while to run, and is not idempotent: it will reformat code and add copyright notices if necessary.
-
-## Development Conventions
-
-### Code Style and Formatting
-
-- The project follows the linting rules in the `analysis_options.yaml` file at the top of the repo.
-- Code formatting is enforced using the `dart_format` tool.
-- The `tool/run_all_tests_and_fixes.sh` script should be run before committing to ensure all files are correctly formatted and analyzed.  Don't run it every time you want to test something, just before you commit, since it does more than just test things, and takes a while.
-
-### Testing
-
-- Widget and unit tests are located in the `test` directory of each package/example.
-- Tests are run using `flutter test`.
-- The CI pipeline, defined in `.github/workflows/flutter_packages.yaml`, runs tests for all packages on every push and pull request to the `main` branch.
-
-### Copyright Headers
-
-- All files must have a copyright header.
-- The `tool/fix_copyright.sh` script (which is called by `run_all_tests_and_fixes.sh`) can be used to automatically add or update copyright headers.
-
-### Firebase Integration
-
-- The examples and the `genui_firebase_ai` package use Firebase.
-- A script at `tool/stub_firebase_options.sh` is used in CI to create a stub `firebase_options.dart` file. For local development, developers need to configure their own Firebase project by following the instructions in [`packages/genui/README.md`](packages/genui/README.md#configure-firebase-ai-logic).
-
-## Updating the Guides (`packages/genui/.guides`)
-
-When asked to update the developer guides located in `packages/genui/.guides`, it is critical to ensure the documentation accurately reflects the current state of the codebase. Before making any changes to the guides, you must read *all* the Dart code in the following packages:
-
--   `packages/genui`
--   `packages/genui_firebase_ai`
--   `packages/genui_google_generative_ai`
--   `packages/genui_a2ui`
-
-This ensures that any code examples, API references, and architectural explanations in the guides are up-to-date and consistent with the actual implementation.
-
-## Draft pull requests
-
-Do not review pull requests when they are in draft state. Wait them to be ready for review.
+Follow the specifications in `specs/README.md`.

.gemini/README.md

@@ -9,7 +9,6 @@ The files in this directory are used to customize the behavior of these tools fo
 
 - **`GEMINI.md`**: Provides project-specific context, instructions, and guidelines that are included in the context when using Gemini CLI and Code Assist. This helps the AI understand the project's conventions and requirements.
 - **`config.yaml`**: Configuration for the Gemini for GitHub tools, such as settings for code review.
-- **`styleguide.md`**: Contains the project's style guide, which is used by the Gemini for Github tools to ensure that generated reviews adhere to the project's conventions.
 - **`commands/`**: A directory containing custom command definitions (e.g., `fix_code.toml`) for the Gemini CLI.
 
 ## Documentation

specs/README.md

@@ -0,0 +1,37 @@
+# GenUI specifications
+
+This folder (./specs) provides technical specifications for the GenUI repository,
+targeted at both AI models and human developers.
+
+## Index of Specifications
+
+This directory contains the following specifications:
+
+- [Style Guide](styleguide.md)
+
+## Note for AI models
+
+If you are an AI model, please read all the specifications in this folder, and follow them carefully.
+To signal, that you have read and understood the specifications, please start your reviews and responses with the following text:
+
+```
+I have read and understood the specifications in ./specs.
+```
+
+## Documentation
+
+1. Documentation in the repository (all .md files) should be clear, consistent, concise and up-to-date.
+2. Documentation should not contain details that are easy to infer from the code.
+3. If code does not match the documentation, there should be TODO comments in the code to signal the discrepancy should be resolved.
+
+## Code reviews
+
+Do not review pull requests when they are in draft state, unless explicitly requested by the author.
+
+## Key commands
+
+- **Run all checks and tests:**
+
+  ```bash
+  ./tool/run_all_tests_and_fixes.sh
+  ```