Improve doc organization.

[polina-c]

No description provided.

[gemini-code-assist]

Code Review

This pull request reorganizes documentation and assets by moving them to more appropriate directories. While the structure is improved, moving docs/DESIGN.md to specs/design.md breaks the relative image links on lines 24 and 28; these should be updated to ../assets/ to point to the new root-level assets folder. Additionally, the repository style guide expects a specs/README.md file, so renaming specs/design.md accordingly would ensure compliance. Finally, there is a versioning inconsistency in the title of docs/migration/migration_0.7.0_to_0.9.0.md, which incorrectly references version 0.8.0 in its main header.

[gspencergoog]

I think the assets folder should stay within docs. They are assets just for the docs, not something that needs to be at the top level (nothing else will use them), and it means all the links have to climb out of the directory to find the assets (e.g. "../assets/foo.png").

The design.md file is not really a specification, it's just detailed documentation of the design, which is why I put it into the docs folder. An agent will still see it in the docs folder, so it should have the same effect for them.

I actually question that the specs folder should be called that, since the things in it aren't specifications, really. It seems more like information for contributors.

[polina-c]

I think the assets folder should stay within docs. They are assets just for the docs, not something that needs to be at the top level (nothing else will use them), and it means all the links have to climb out of the directory to find the assets (e.g. "../assets/foo.png").

The design.md file is not really a specification, it's just detailed documentation of the design, which is why I put it into the docs folder. An agent will still see it in the docs folder, so it should have the same effect for them.

I actually question that the specs folder should be called that, since the things in it aren't specifications, really. It seems more like information for contributors.

Yes! Let's find structure that we both like.

I would like to see clear separation:

1. Documents for users (human or AI), 'docs' in this PR
2. Documents for contributors (human or AI), 'specs' in this PR

We also have assets that contain assets for both folders above.

This is another option to structure the docs:

• docs
  • usage
  • contributing
  • assets

Thoughts?

[gspencergoog]

This is another option to structure the docs:

• docs
  • usage
  • contributing
  • assets

Yes, let's put it all under docs. That sounds like a good organization.

[polina-c]

Thanks, applied.

[gspencergoog]

Can we move specs into the docs folder too? Then all the docs will be in one place.

[polina-c]

/gemini review

Verify links to assets are not broken and all assets are used.

[gemini-code-assist]

Code Review

The pull request improves documentation organization by renaming and moving several documentation files into more logical directories, and by removing outdated launch configurations. The changes enhance clarity and maintainability of the project's documentation structure. The removal of the extra blank line in run_app_with_gemini_key.md is a good cleanup. The changes to README.md to reflect the new documentation path are also appropriate.

I am having trouble creating individual review comments. Click here to see my feedback.

.vscode/launch.json (31-47)

These launch configurations for custom_backend and tic_tac_toe (dartantic) have been removed. If these examples are no longer relevant or maintained, their removal is appropriate for cleaning up the development environment. However, if these are still valid examples that should be runnable, they should be updated to reflect the current project structure or kept if they are still functional.

[polina-c]

/gemini

These launch configurations for custom_backend and tic_tac_toe (dartantic) have been removed. If these examples are no longer relevant or maintained, their removal is appropriate for cleaning up the development environment. However, if these are still valid examples that should be runnable, they should be updated to reflect the current project structure or kept if they are still functional.

Can you verify the examples do not exist any more?