docs: describe what the actor interface file declares

docs/src/content/docs/structure.md

@@ -632,4 +632,6 @@ This type is the same types that the [`init` function](#init-function-1) returns
 
 ### `<service-name>.d.ts`
 
-This file contains the same TypeScript types as [`<service-name>.ts`](#service-namets). It is typically used to add to LLMs' contexts' to give knowledge about what types are available in the service. Set the [`output.actor.interfaceFile`](./core/api/type-aliases/GenerateOutputOptions.md#interfaceFile) option to `true` to generate this file.
+This file declares the types of [`<service-name>.ts`](#service-namets): the candid types, the `Some`, `None` and `Option` types, the [`<service-name>Interface` type](#service-nameinterface-type), `CreateActorOptions` and the [`createActor` function](#createactor-function). It leaves out the [`<service-name>` class](#service-name-class), so `createActor` is declared to return `<service-name>Interface` instead. The class implements that interface, so code written against this file also compiles against `<service-name>.ts`.
+
+The file is a reference, typically added to LLMs' contexts to give knowledge about what types are available in the service. It is not meant to be imported: it is only generated next to `<service-name>.ts`, and an import of `./<service-name>` resolves to that file. Set the [`output.actor.interfaceFile`](./core/api/type-aliases/GenerateOutputOptions.md#interfaceFile) option to `true` to generate it.

src/cli/icp-bindgen.ts

@@ -39,7 +39,7 @@
  *
  * - `--did-file <path>`: Path to the `.did` file to generate bindings from
  * - `--out-dir <dir>`: Directory where the bindings will be written
- * - `--actor-interface-file`: If set, generates a `<service-name>.d.ts` file that contains the same types of the `<service-name>.ts` file. Has no effect if `--actor-disabled` is set. (default: `false`)
+ * - `--actor-interface-file`: If set, generates a `<service-name>.d.ts` file that declares the types of the `<service-name>.ts` file without the `<service-name>` class: its `createActor` returns the `<service-name>Interface` type. Has no effect if `--actor-disabled` is set. (default: `false`)
  * - `--actor-disabled`: If set, skips generating the actor file (`<service-name>.ts`). (default: `false`)
  * - `--declarations-flat`: If set, generates declaration files directly in the output directory instead of in a `declarations/` subfolder. (default: `false`)
  * - `--force`: If set, overwrite existing files instead of aborting. (default: `false`)
@@ -108,7 +108,7 @@ program
   .option('--actor-disabled', 'If set, skips generating the actor file (<service-name>.ts).', false)
   .option(
     '--actor-interface-file',
-    'If set, generates a `<service-name>.d.ts` file that contains the same types of the `<service-name>.ts` file. Has no effect if `--actor-disabled` is set.',
+    'If set, generates a `<service-name>.d.ts` file that declares the types of the `<service-name>.ts` file without the `<service-name>` class: its `createActor` returns the `<service-name>Interface` type. Has no effect if `--actor-disabled` is set.',
     false,
   )
   .option(

src/core/generate/index.ts

@@ -30,8 +30,8 @@ export type GenerateOutputOptions = {
     | {
         disabled?: false;
         /**
-         * If `true`, generates a `<service-name>.d.ts` file that contains the same types of the `<service-name>.ts` file.
-         * Useful to add to LLMs' contexts' to give knowledge about what types are available in the service.
+         * If `true`, generates a `<service-name>.d.ts` file that declares the types of the `<service-name>.ts` file without the `<service-name>` class: its `createActor` returns the `<service-name>Interface` type.
+         * Useful to add to LLMs' contexts to give knowledge about what types are available in the service.
          *
          * Has no effect if `disabled` is `true`.
          *