add reference info for composition.yaml and .crd-sources.yaml

docs-site/content/en/docs/reference/_index.md

@@ -13,3 +13,5 @@ in function-hcl.
 - [Built-in Functions](./built-in-functions/) -- the available function library
 - [Error Conditions](./error-conditions/) -- every error the function can produce
 - [fn-hcl-tools CLI](./fn-hcl-tools/) -- companion CLI for packaging and analysis
+- [composition.yaml](./composition-yaml/) -- composition metadata: composite type and library files
+- [.crd-sources.yaml](./crd-sources-yaml/) -- language server CRD source configuration

docs-site/content/en/docs/reference/composition-yaml.md

@@ -0,0 +1,77 @@
+---
+title: "composition.yaml"
+linkTitle: "composition.yaml"
+weight: 5
+description: >
+  Reference for the composition.yaml metadata file.
+---
+
+`composition.yaml` is an optional metadata file placed in the same directory as your `.hcl` files.
+It tells function-hcl tools and the language server about the composition's composite type and any
+shared library files the composition depends on.
+
+## Location
+
+Place `composition.yaml` in the root of your composition directory, alongside your `.hcl` files:
+
+```
+my-composition/
+  composition.yaml
+  main.hcl
+  resources.hcl
+```
+
+## Fields
+
+```yaml
+xrd:
+  apiVersion: <string>
+  kind: <string>
+
+libraryFiles:
+  - <relative-path>
+```
+
+### `xrd`
+
+Declares the composite type (XRD) that this composition targets.
+The language server uses these values to look up the XRD schema and provide completions
+for the built-in `composite` variable.
+
+Both fields are optional but must both be non-empty for the language server to use them.
+
+| Field        | Type   | Description                                          |
+|--------------|--------|------------------------------------------------------|
+| `apiVersion` | string | API version of the composite type, e.g. `example.io/v1` |
+| `kind`       | string | Kind of the composite type, e.g. `XPostgresInstance` |
+
+### `libraryFiles`
+
+A list of HCL files outside the composition directory that are included when the composition
+is packaged with `fn-hcl-tools package`. Paths are relative to the `composition.yaml` file
+and must not be absolute. Directories are not allowed.
+
+This is useful for sharing common HCL helpers across multiple compositions:
+
+```yaml
+libraryFiles:
+  - ../shared/helpers.hcl
+  - ../shared/tags.hcl
+```
+
+## Example
+
+```yaml
+xrd:
+  apiVersion: database.example.io/v1alpha1
+  kind: XPostgresInstance
+
+libraryFiles:
+  - ../lib/common-tags.hcl
+```
+
+## Behaviour when absent
+
+If `composition.yaml` is absent, function-hcl tools process all `.hcl` files in the directory
+with no library files and no XRD type information. The language server still provides completions
+for resource types, but cannot provide completions for `composite` fields.

docs-site/content/en/docs/reference/crd-sources-yaml.md

@@ -0,0 +1,82 @@
+---
+title: ".crd-sources.yaml"
+linkTitle: ".crd-sources.yaml"
+weight: 6
+description: >
+  Reference for the .crd-sources.yaml language server configuration file.
+---
+
+`.crd-sources.yaml` is an optional configuration file that tells the language server where to find
+CRD and XRD YAML files, and which resource scopes to include in completions.
+It is the advanced alternative to placing files directly in a [`.crds/` directory](../../getting-started/crd-setup#simple-setup-the-crds-directory).
+
+## Location
+
+Place `.crd-sources.yaml` in the root of your compositions repository (or any ancestor directory).
+The language server walks up the directory tree from the open file and uses the first
+`.crd-sources.yaml` it finds. If none is found, it falls back to looking for a `.crds/` directory.
+
+```
+repo-root/
+  .crd-sources.yaml   ← found for all compositions below
+  compositions/
+    postgres/
+      composition.hcl
+    redis/
+      composition.hcl
+```
+
+## Fields
+
+```yaml
+scope: <"namespaced" | "cluster" | "both">
+
+paths:
+  - <path-or-glob>
+```
+
+### `scope`
+
+Controls which resource scopes are included in completions.
+
+| Value         | Description                                                  |
+|---------------|--------------------------------------------------------------|
+| `both`        | Include all resources regardless of scope. **(default)**    |
+| `namespaced`  | Include only namespace-scoped resources.                     |
+| `cluster`     | Include only cluster-scoped resources.                       |
+
+When omitted, `both` is used.
+
+### `paths`
+
+A list of file paths or glob patterns pointing to YAML files that contain CRD or XRD definitions.
+Relative paths are resolved from the directory that contains `.crd-sources.yaml`.
+Absolute paths are also supported.
+
+The `**` double-star glob matches across directory boundaries:
+
+```yaml
+paths:
+  - .crds/*.yaml               # all YAML files directly in .crds/
+  - crds/**/*.yaml             # all YAML files anywhere under crds/
+  - /shared/platform-crds/*.yaml  # absolute path
+```
+
+Only `.yaml` files are loaded; other extensions are silently skipped.
+
+## Example
+
+```yaml
+scope: both
+paths:
+  - .crds/*.yaml
+  - ../shared/xrds/*.yaml
+```
+
+## Behaviour
+
+The language server loads the matching files in the background when you open an HCL file.
+It watches for changes to the matched files and reloads automatically — no restart required.
+
+If `.crd-sources.yaml` exists but `paths` matches no files, completions for dynamic resource
+types will be empty until matching files are added.