docs: update readme (#574)

* docs: update readme

* docs: update readme and start api helper script

README.md

@@ -1,52 +1,59 @@
-# Io Crossword
+# I/O Crossword
+
+[![I/O Crossword Header][header]][io_crossword_link]
 
 ![coverage][coverage_badge]
 [![style: very good analysis][very_good_analysis_badge]][very_good_analysis_link]
-[![License: MIT][license_badge]][license_link]
 
-Generated by the [Very Good CLI][very_good_cli_link] 🤖
+The crossword game built with the [Gemini API][gemini_api_link], [Flutter][flutter_link] and [Firebase][firebase_link] for [Google I/O 2024][google_io_link].
+
+_Built by [Very Good Ventures][very_good_ventures_link] in partnership with Google._
 
-Google I/O Crossword game
+_Created using [Very Good CLI][very_good_cli_link] 🤖_
 
 ---
 
 ## Getting Started 🚀
 
 This project has different entry points.
 
->Note: The environment variables are available in the project vault.
-
 - `main_local.dart` that targets a local api that should be run first (see how to do it [here][api_readme]).
 
 ```sh
-$ flutter run -d chrome --target lib/main_local.dart --web-port 24514 --dart-define RECAPTCHA_KEY=<RECAPTCHA_KEY> --dart-define APPCHECK_DEBUG_TOKEN=<APPCHECK_DEBUG_TOKEN>
+$ flutter run -d chrome --target lib/main_local.dart --web-port 24514 --dart-define RECAPTCHA_KEY=<RECAPTCHA_KEY> --dart-define APPCHECK_DEBUG_TOKEN=<APPCHECK_DEBUG_TOKEN> --dart-define CROSSWORD_URL=https://crossword.withgoogle.com
 ```
 
+The specified web port is just an example that matches with the one set in the [helper script][start_api_script] to run the api.
+
 - `main_development.dart` that targets the dev api.
 
 ```sh
-$ flutter run -d chrome --target lib/main_development.dart --dart-define RECAPTCHA_KEY=<RECAPTCHA_KEY> --dart-define APPCHECK_DEBUG_TOKEN=<APPCHECK_DEBUG_TOKEN>
+$ flutter run -d chrome --target lib/main_development.dart --dart-define RECAPTCHA_KEY=<RECAPTCHA_KEY> --dart-define APPCHECK_DEBUG_TOKEN=<APPCHECK_DEBUG_TOKEN> --dart-define CROSSWORD_URL=https://crossword.withgoogle.com
 ```
 
 - `main_debug.dart` that targets the dev api and adds a visual layer to debug the crossword sections, their position, fps and other items.
 
 ```sh
-$ flutter run -d chrome --target lib/main_debug.dart --dart-define RECAPTCHA_KEY=<RECAPTCHA_KEY> --dart-define APPCHECK_DEBUG_TOKEN=<APPCHECK_DEBUG_TOKEN>
+$ flutter run -d chrome --target lib/main_debug.dart --dart-define RECAPTCHA_KEY=<RECAPTCHA_KEY> --dart-define APPCHECK_DEBUG_TOKEN=<APPCHECK_DEBUG_TOKEN> --dart-define CROSSWORD_URL=https://crossword.withgoogle.com
 ```
 
 - `main_staging.dart` that targets the staging api.
 
 ```sh
-$ flutter run -d chrome --target lib/main_staging.dart --dart-define RECAPTCHA_KEY=<RECAPTCHA_KEY>
+$ flutter run -d chrome --target lib/main_staging.dart --dart-define RECAPTCHA_KEY=<RECAPTCHA_KEY> --dart-define CROSSWORD_URL=https://crossword.withgoogle.com
 ```
 
 - `main_production.dart` that targets the production api.
 
 ```sh
-$ flutter run -d chrome --target lib/main_production.dart --dart-define RECAPTCHA_KEY=<RECAPTCHA_KEY>
+$ flutter run -d chrome --target lib/main_production.dart --dart-define RECAPTCHA_KEY=<RECAPTCHA_KEY> --dart-define CROSSWORD_URL=https://crossword.withgoogle.com
 ```
 
-_\*Io Crossword works on Web._
+_\*I/O Crossword works on Web._
+
+### Environment variables
+
+The `RECAPTCHA_KEY` and `APPCHECK_DEBUG_TOKEN` environment variables are used to make the app more secure with [Firebase App Check][app_check_link]. You will have to [register your site for reCAPTCHA v3][recaptcha_link] and get a key.
 
 ---
 
@@ -184,9 +191,17 @@ Alternatively, run `flutter run` and code generation will take place automatical
 [coverage_badge]: coverage_badge.svg
 [flutter_localizations_link]: https://api.flutter.dev/flutter/flutter_localizations/flutter_localizations-library.html
 [internationalization_link]: https://flutter.dev/docs/development/accessibility-and-localization/internationalization
-[license_badge]: https://img.shields.io/badge/license-MIT-blue.svg
-[license_link]: https://opensource.org/licenses/MIT
 [very_good_analysis_badge]: https://img.shields.io/badge/style-very_good_analysis-B22C89.svg
 [very_good_analysis_link]: https://pub.dev/packages/very_good_analysis
 [very_good_cli_link]: https://github.com/VeryGoodOpenSource/very_good_cli
 [api_readme]: api/README.md
+[very_good_ventures_link]: https://verygood.ventures/
+[header]: art/readme_header.png
+[io_crossword_link]: https://crossword.withgoogle.com/
+[google_io_link]: https://io.google/2024/
+[flutter_link]: https://flutter.dev/
+[firebase_link]: https://firebase.google.com/
+[gemini_api_link]: https://ai.google.dev/
+[app_check_link]: https://firebase.google.com/docs/app-check/flutter/default-providers
+[recaptcha_link]: https://www.google.com/recaptcha/admin/create
+[start_api_script]: api/scripts/start_local_api.sh

api/README.md

@@ -9,13 +9,16 @@ Built with dart_frog.
 
 # Running
 
-To run the API the following arguments needs to be passed:
+To run the API you can use the helper [`start_local_api.sh`][start_api_script] script.
 
-```
+Alternatively, you can manually pass the following arguments:
+
+```sh
 FB_APP_ID=APP_ID \
-INITIALS_BLACKLIST_ID=ID \
+INITIALS_BLACKLIST_ID=DOCUMENT_ID \
 FB_STORAGE_BUCKET=FIREBASE_BUCKET_NAME \
 GAME_URL=http://localhost:24514 \
+HINT_FUNCTION_URL=FIREBASE_FUNCTION_URL \
 dart_frog dev
 ```
 
@@ -32,3 +35,4 @@ To configure it to be able to receive request, do the following:
 [license_link]: https://opensource.org/licenses/MIT
 [very_good_analysis_badge]: https://img.shields.io/badge/style-very_good_analysis-B22C89.svg
 [very_good_analysis_link]: https://pub.dev/packages/very_good_analysis
+[start_api_script]: scripts/start_local_api.sh

scripts/start_local_api.sh → api/scripts/start_local_api.sh

@@ -11,4 +11,4 @@ echo ' ######################## '
 echo ' ## Starting dart frog ## '
 echo ' ######################## '
 
-cd api && dart_frog dev
+dart_frog dev