[sync] 2026/03/24

.agents/skills/stage-site/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: stage-site
+description: >-
+  Stages the Flutter site locally. This includes checking for broken links,
+  verifying excerpts, updating formatting, and serving the dev site.
+---
+
+# Stage the Flutter site
+
+Before committing changes or reviewing a PR locally,
+it is important to stage the site and ensure everything works correctly. 
+Follow these steps to stage the site:
+
+## 1. Check for broken links
+
+Run the following command to check for any unlinked or broken
+Markdown link references in the site output:
+
+```bash
+dart run dash_site check-link-references
+```
+
+Alternatively, to verify all links between pages on the site work:
+
+```bash
+dart run dash_site check-links
+```
+
+If any broken links are found, try to patch them or alert the user.
+
+## 2. Sync code excerpts
+
+Ensure that any changed code excerpts are properly run and synced to the Markdown files:
+
+```bash
+dart run dash_site refresh-excerpts
+```
+
+## 3. Update formatting
+
+Update the formatting of the site examples and tools to ensure
+they follow the official Dart format:
+
+```bash
+dart run dash_site format-dart
+```
+
+## 4. Stage the site locally
+
+Finally, serve a local development server of the site so the user can preview the changes:
+
+```bash
+dart run dash_site serve
+```

.agents/skills/update-llms-text/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: update-llms-text
+description: Update and maintain the llms.txt file. Use when the user wants to add sections, add links, correct information, or review the llms.txt file.
+disable-model-invocation: true
+argument-hint: "[action or description of changes]"
+---
+
+# Update llms.txt
+
+Update `src/content/llms.txt`, a curated resource list that
+helps LLMs understand the Flutter framework.
+
+Always start by reading the existing `src/content/llms.txt` to
+understand the current structure and content before making changes.
+
+## Actions
+
+Based on the user-provided action, perform one of the following tasks:
+
+### Add a section
+
+When asked to add a new section:
+
+1.  If not provided, ask for the section title and links.
+2.  Place the new section in a logical location relative to existing sections.
+
+### Add links
+
+When asked to add new links to an existing section:
+
+1.  If not provided, ask for the target section and links to add.
+2.  For each link provided:
+
+    1.  Load and analyze its source file to identify its title and
+        determine an appropriate description.
+    2.  Append the link to the specified section,
+        matching the existing Markdown-based format:
+
+        ```md
+        - [Title](URL): Description.
+        ```
+
+### Correct information
+
+When asked to correct information:
+
+1.  If not provided, Ask for the incorrect information and the correction.
+2.  Update the file with the corrected information.
+
+### Review the file
+
+When asked to review the file:
+
+1.  Read the entire file.
+2.  Check for duplicate entries, broken links, inconsistent formatting,
+    spelling and grammar errors, and general opportunities for improvement.
+3.  Report findings and suggestions to the user, but
+    don't make changes without approval.
+
+## Formatting rules
+
+- Each link follows the format: `- [Title](URL): Description.`
+- Sections are separated by a blank line.
+- Keep descriptions concise and informative.

.agents/skills/validate-pr/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: validate-pr
+description: >-
+  Stages the Flutter site locally. This includes checking for broken links,
+  verifying excerpts, updating formatting, and serving the dev site.
+---
+
+# Stage the Flutter site
+
+Before committing changes or reviewing a PR locally,
+it is important to stage the site and ensure everything works correctly. 
+Follow these steps to stage the site:
+
+## 1. Sync code excerpts
+
+Ensure that any changed code excerpts are properly run and synced to the
+Markdown files:
+
+```bash
+dart run dash_site refresh-excerpts
+```
+
+## 2. Update formatting
+
+Update the formatting of the site examples and tools to ensure
+they follow the official Dart format:
+
+```bash
+dart run dash_site format-dart
+```
+
+## 3. Check for broken links
+
+Run the following command to check for any unlinked or broken
+Markdown link references in the site output:
+
+```bash
+dart run dash_site check-link-references
+```
+
+If any broken links are found, try to patch them or alert the user.
+
+## 4. Stage the site locally
+
+Finally, serve a local development server of the site so the user can preview the changes:
+
+```bash
+dart run dash_site serve
+```

.gemini/config.yaml

@@ -0,0 +1,17 @@
+# Configuration for the Gemini Code Assist review bot on GitHub.
+# Relevant documentation: https://developers.google.com/gemini-code-assist/docs/customize-gemini-behavior-github
+
+code_review:
+  # Only leave review comments for medium or higher severity issues.
+  comment_severity_threshold: MEDIUM
+  # We don't need to include drafts.
+  pull_request_opened:
+    # The documentation can be referenced if needed.
+    help: false
+    # The summaries are often too verbose to be helpful, and we expect
+    # contributors to provide sufficient detail in the PR description.
+    summary: false
+    include_drafts: false
+
+# We have lots of fun already and less noise is fun too.
+have_fun: false

AGENTS.md

@@ -0,0 +1,73 @@
+# AGENTS.md
+
+This file provides important project context and guidance to
+agentic coding and writing tools when working with them on
+content and code in this repository.
+
+## Project overview
+
+This repository contains the source code and content for
+the Flutter framework's documentation website.
+It is hosted at `docs.flutter.dev` and shouldn't be confused with
+the marketing site at `flutter.dev` or the API docs at `api.flutter.dev`.
+
+The website is statically built and implemented with
+Dart and the [Jaspr](https://jaspr.site) web framework.
+For loading content, data, and some of its assets,
+it uses [Jaspr Content](https://docs.jaspr.site/content).
+
+### Directory structure
+
+- `src/content/`:
+  Markdown-based documentation pages.
+- `src/data/`:
+  YAML and JSON data files used by the site, such as
+  for the sidenav, glossary, and various indices.
+- `src/_includes/`:
+  Liquid partial files written in Markdown.
+- `examples/`:
+  A pub workspace containing Dart and Flutter code examples,
+  referenced by code excerpts in the Markdown files.
+- `site/`:
+  The site implementation written in Dart using Jaspr and Jaspr Content.
+- `tool/dash_site/`:
+  CLI tool for site development and maintenance.
+
+## Common commands
+
+While working on the site,
+you might need to run these commands:
+
+```bash
+# Install or update Dart dependencies:
+dart pub get
+
+# Serve a dev server of the site locally:
+dart run dash_site serve
+
+# Build a production version of the site:
+dart run dash_site build
+
+# Sync code excerpts to Markdown files:
+dart run dash_site refresh-excerpts
+
+# Learn what other commands are available:
+dart run dash_site --help
+```
+
+## Content guidelines
+
+### Writing style
+
+Writing should be consistent across the site and follow the
+[Google developer documentation style guide](https://developers.google.com/style/).
+
+#### Line breaks
+
+In Markdown files, use [semantic line breaks](https://sembr.org/) and
+try to keep each line under 80 characters long.
+
+## Coding guidelines
+
+All Dart code should follow [Effective Dart](https://dart.dev/effective-dart),
+unless purposefully not for explanatory or pedagogical purposes.

README.md

@@ -33,28 +33,28 @@ it's easiest to make changes using the GitHub UI.
 
 If you have an issue with the
 API docs on [api.flutter.dev](https://api.flutter.dev),
-please file those issues on
+please file them on
 the [`flutter/flutter`](https://github.com/flutter/flutter/issues) repo,
 not on this (`flutter/website`) repo.
 The API docs are embedded in Flutter's source code,
-so the engineering team handles those.
+so the engineering team handles them.
 
 
 ## Before you submit a PR
 
 We love it when the community gets involved in improving our docs!
-But here are a few notes to keep in mind before you submit a PR:
+Here are a few things to keep in mind before you submit a PR:
 
 - When triaging issues,
   we sometimes label an issue with the tag **PRs welcome**.
-  But we welcome PRs on other issues as well—
+  However, we welcome PRs on other issues as well—
   it doesn't have to be tagged with that label.
-- Please don't run our docs through Grammarly (or similar)
+- Please don't run our docs through Grammarly (or a similar tool)
   and submit those changes as a PR.
-- We follow the [Google Developer Documentation Style Guidelines][] —
-  for example, don't use "i.e." or "e.g.",
-  avoid writing in first person,
-  and avoid writing in future tense.
+- We follow the [Google Developer Documentation Style Guidelines][]—
+  for example, avoid "i.e." or "e.g.",
+  avoid writing in the first person,
+  and avoid the future tense.
   You can start with the
   [style guide highlights](https://developers.google.com/style/highlights)
   or the [word list](https://developers.google.com/style/word-list),
@@ -76,7 +76,7 @@ Often you can make changes using the GitHub UI.
 If needed, we can stage the changes automatically in your pull request.
 
 If your change involves code samples, adds/removes pages, or affects navigation,
-do consider building and testing your work before submitting.
+please build and test your work before submitting.
 
 If you want or need to build the site, follow the steps below.
 
@@ -94,8 +94,8 @@ install the latest stable release of Flutter, which includes Dart.
 If you don't have Flutter or need to update, follow the
 instructions at [Install Flutter][] or [Upgrading Flutter][].
 
-If you already have Flutter installed, verify it's on your path
-and already the latest stable version:
+If you already have Flutter installed, verify it's in your path
+and is the latest stable version:
 
 ```console
 flutter --version
@@ -122,7 +122,7 @@ git clone https://github.com/flutter/website.git
 ## Set up your local environment and serve changes
 
 Before you continue setting up the site infrastructure,
-verify the correct versions of Flutter are set up and available by
+verify that the correct version of Flutter is set up and available by
 following the instructions in [Get the prerequisites](#get-the-prerequisites).
 
 1. _Optional:_ After cloning the repo,
@@ -181,27 +181,27 @@ following the instructions in [Get the prerequisites](#get-the-prerequisites).
 
 If you've made changes to the code in
 the `/examples`, `/site`, or `/tool` directories,
-commit your work, then run the following command to
-verify it is up to date and matches the site standards.
+commit your work, and then run the following command to
+verify that it is up to date and matches site standards.
 
 ```terminal
 dart run dash_site check-all
 ```
 
 If this script reports any errors or warnings,
-then address those issues and rerun the command.
-If you have any issues, leave a comment on your issue or pull request,
-and we'll try our best to help you.
+address them and rerun the command.
+If you have questions, leave a comment on your issue or pull request,
+and we'll do our best to help.
 You can also chat with us on the `#hackers-devrel` channel
 on the [Flutter contributors Discord][]!
 
 [Flutter contributors Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
 
 ### Check links
 
-If you've made changes to the content and would like to check all
-internal links are functional and Markdown link references are valid,
-build the site locally and then run the following commands.
+If you've made changes to the content and want to check that all
+internal links and Markdown link references are valid,
+build the site locally and run the following commands.
 
 1.  Build the site locally.
 
@@ -215,7 +215,7 @@ build the site locally and then run the following commands.
     dart run dash_site check-link-references
     ```
 
-1.  Validate all internal links are valid.
+1.  Verify that all internal links are valid.
 
     > [!NOTE]
     > This command relies on the `firebase` CLI tool being on your PATH.
@@ -227,14 +227,14 @@ build the site locally and then run the following commands.
     ```
 
 If either command reports any errors or warnings,
-then address those issues, rebuild the site, and rerun the command.
+address them, rebuild the site, and rerun the command.
 
 [firebase-install]: https://firebase.google.com/docs/cli#setup_update_cli
 
 ### Refresh code excerpts
 
 A build that fails with the error
-`Error: Some code excerpts needed to be updated!`
+`Error: Some code excerpts need to be updated!`
 means that one or more code excerpts in the site Markdown files
 aren't identical to the code regions declared
 in the corresponding `.dart` files.
@@ -250,4 +250,4 @@ run `dart run dash_site refresh-excerpts`.
 To learn more about creating, editing, and using code excerpts,
 check out the [excerpt updater package documentation][].
 
-[excerpt updater package documentation]: https://github.com/dart-lang/site-shared/tree/main/pkgs/excerpter#readme
+[excerpt updater package documentation]: https://github.com/flutter/website/tree/main/packages/excerpter#readme