Move guide docs under docs/guides and keep docs README at root

Author: pchalamet

README.md

@@ -36,7 +36,7 @@ FScript currently includes:
 
 If you are new to FScript, start with the progressive tutorial:
 
-- [`docs/getting-started-tutorial.md`](docs/getting-started-tutorial.md)
+- [`docs/guides/getting-started-tutorial.md`](docs/guides/getting-started-tutorial.md)
 
 It covers installation, syntax basics, flow control, collections, pattern matching, stdlib usage, includes, and host/export concepts.
 
@@ -129,10 +129,10 @@ See [`docs/specs/sandbox-and-security.md`](docs/specs/sandbox-and-security.md) f
 ## Documentation
 
 - Documentation portal: [`docs/README.md`](docs/README.md)
-- Tutorial: [`docs/getting-started-tutorial.md`](docs/getting-started-tutorial.md)
+- Tutorial: [`docs/guides/getting-started-tutorial.md`](docs/guides/getting-started-tutorial.md)
 - Specifications index: [`docs/specs/README.md`](docs/specs/README.md)
 - Architecture index: [`docs/architecture/README.md`](docs/architecture/README.md)
-- FScript vs F# / OCaml: [`docs/fsharp-ocaml-differences.md`](docs/fsharp-ocaml-differences.md)
+- FScript vs F# / OCaml: [`docs/guides/fsharp-ocaml-differences.md`](docs/guides/fsharp-ocaml-differences.md)
 
 ## Changelog
 

docs/README.md

@@ -2,15 +2,15 @@
 
 This folder is organized into three layers:
 
-- Getting started and comparative docs (this folder)
+- Getting started and comparative docs (`docs/guides/`)
 - Language behavior specifications: [`docs/specs/`](./specs/README.md)
 - Internal structure and component design: [`docs/architecture/`](./architecture/README.md)
 
 ## Start here
 
-- Tutorial: [`getting-started-tutorial.md`](./getting-started-tutorial.md)
-- FScript vs F# / OCaml: [`fsharp-ocaml-differences.md`](./fsharp-ocaml-differences.md)
-- Language rationale: [`language-choices.md`](./language-choices.md)
+- Tutorial: [`guides/getting-started-tutorial.md`](./guides/getting-started-tutorial.md)
+- FScript vs F# / OCaml: [`guides/fsharp-ocaml-differences.md`](./guides/fsharp-ocaml-differences.md)
+- Language rationale: [`guides/language-choices.md`](./guides/language-choices.md)
 
 ## Deep dives
 

docs/fsharp-ocaml-differences.md docs/guides/fsharp-ocaml-differences.mddocs/fsharp-ocaml-differences.md renamed to docs/guides/fsharp-ocaml-differences.md

@@ -322,7 +322,7 @@ let hasA = m |> Map.containsKey "a"
 ```
 
 Full reference:
-- [`docs/specs/stdlib-functions.md`](./specs/stdlib-functions.md)
+- [`docs/specs/stdlib-functions.md`](../specs/stdlib-functions.md)
 
 ## 10. Includes and modules
 You can split scripts using `#include`.
@@ -372,16 +372,16 @@ When embedding, keep this mindset:
 - expose only needed externs,
 - keep filesystem/network boundaries explicit,
 - use host-level timeout/cancellation/resource limits.
-- see [`docs/specs/embedding-fscript-language.md`](./specs/embedding-fscript-language.md) for the embedding API,
-- see [`docs/specs/external-functions.md`](./specs/external-functions.md) for extern design/registration,
-- see [`docs/specs/sandbox-and-security.md`](./specs/sandbox-and-security.md) for the full security model.
+- see [`docs/specs/embedding-fscript-language.md`](../specs/embedding-fscript-language.md) for the embedding API,
+- see [`docs/specs/external-functions.md`](../specs/external-functions.md) for extern design/registration,
+- see [`docs/specs/sandbox-and-security.md`](../specs/sandbox-and-security.md) for the full security model.
 
 ## 12. Next steps
 - Sample scripts:
-  - [`samples/types-showcase.fss`](../samples/types-showcase.fss)
-  - [`samples/patterns-and-collections.fss`](../samples/patterns-and-collections.fss)
-  - [`samples/map-matching.fss`](../samples/map-matching.fss)
-  - [`samples/includes-and-exports.fss`](../samples/includes-and-exports.fss)
-- Specifications index: [`docs/specs/README.md`](./specs/README.md)
-- Architecture index: [`docs/architecture/README.md`](./architecture/README.md)
-- [`samples/`](../samples/)
+  - [`samples/types-showcase.fss`](../../samples/types-showcase.fss)
+  - [`samples/patterns-and-collections.fss`](../../samples/patterns-and-collections.fss)
+  - [`samples/map-matching.fss`](../../samples/map-matching.fss)
+  - [`samples/includes-and-exports.fss`](../../samples/includes-and-exports.fss)
+- Specifications index: [`docs/specs/README.md`](../specs/README.md)
+- Architecture index: [`docs/architecture/README.md`](../architecture/README.md)
+- [`samples/`](../../samples/)