Split AGENTS.md into area guides so Codex reads it in full again (#1046)

2026-10-12 05:33:48 +00:00 · 2026-10-11 11:22:40 +02:00
1 parent 8badadb35f
commit 3a1f586f76
@@ -0,0 +1,15 @@
+# AGENTS.md
+
+These instructions cover the model knowledge in `app/MindWork AI Studio/Models/`. They add to the
+`AGENTS.md` in the repository root, which applies here as well.
+
+## Model Capabilities
+
+When adding, changing, or removing model knowledge, keep these parts in sync:
+- `app/MindWork AI Studio/Models/<Vendor>/<Family>.cs` for the family itself. Creating the class is enough — the source generator in `app/SourceGeneratedMappings/` collects every non-abstract `ModelFamily` and `IModelHost` at compile time, so there is no registration list. Do not add reflection here; `PublishTrimmed` is on.
+- `app/Tests/Models/Corpus/` for the model IDs the family covers, marked as either unchanged or expected to change. A porting difference which nobody declared is what the corpus exists to catch.
+- `app/MindWork AI Studio/Models/Kinds/` when the change is about what kind of model something is, rather than what it can do. These are ordinary rules of the same engine.
+- `app/MindWork AI Studio/Models/Hosting/Hosts/` when a provider wraps model names or cannot pass an API through. A host unwraps and trims the transport; it states nothing about the model itself.
+- `app/MindWork AI Studio/Plugins/models/plugin.lua` when a new field can be declared by an organization, and `app/MindWork AI Studio/Plugins/configuration/plugin.lua` when it can be overridden per provider instance.
+
+Rules are never tried in order: specificity is computed from the rule, and two rules of equal specificity on one name fail the test suite. State how a model reasons with `Reasoning(...)` — the three reasoning capabilities are override vocabulary and must never appear in a profile. Every family and every host has to name the page it was read from and the day somebody read it; `dotnet run verify-models` reports the ones which have gone stale.
@@ -0,0 +1 @@
+@AGENTS.md
@@ -0,0 +1,33 @@
+# AGENTS.md
+
+These instructions cover the databases in `app/MindWork AI Studio/Tools/Databases/`. They add to the
+`AGENTS.md` in the repository root, which applies here as well.
+
+## Databases
+
+Local RAG runs on two databases, addressed through `DatabaseRole`:
+
+- **`VECTOR_STORE`** — Qdrant Edge through the `qdrant-edge` crate, running **in-process inside the
+  Rust runtime**. There is no sidecar process, no port 6333 and no Qdrant API key; .NET reaches it
+  over the internal runtime API (`/system/qdrant-edge/*`, see `runtime/src/qdrant_edge_database.rs`),
+  secured by the same TLS and API token as every other runtime call. One store per data source,
+  named `rag_<data source guid>`, holding a single named vector `embedding` per point.
+- **`INDEX_STORE`** — SQLite at `<data directory>/databases/sqlite/rag-index.sqlite3`, reached
+  through EF Core. It holds the data sources, the file fingerprints, the chunk texts and an FTS5
+  index over them, plus the files which permanently failed to index.
+
+When working on these, keep in mind:
+
+- **`GetDisplayInfo()` feeds the information page.** A new diagnostic value belongs in the client
+  that knows it, not in `Pages/Information.razor.cs`. The page renders whatever label-value pairs it
+  receives and stays free of per-database knowledge.
+- **Let every probe in `GetDisplayInfo()` catch its own failure.** When the method throws, the page
+  replaces the *entire* block with the fallback client, so one unreadable value costs all the others
+  as well.
+- **Raw SQL against SQLite goes through `context.Database.GetDbConnection()`**, not through
+  `SqlQueryRaw<T>`: that one expects a column named `Value` and wraps the statement, so a `PRAGMA`
+  never works with it.
+- **A new EF Core migration needs a `[DynamicDependency]`** in `IndexStoreSchemaMigrator`, because
+  `PublishTrimmed` is on and the migration type would otherwise be trimmed away. The "Schema version"
+  line on the information page shows the applied and pending counts, so a forgotten entry becomes
+  visible there.
@@ -0,0 +1 @@
+@AGENTS.md
@@ -0,0 +1,26 @@
+# AGENTS.md
+
+These instructions cover the plugin system in `app/MindWork AI Studio/Tools/PluginSystem/` and what
+configuration plugins can provide. They add to the `AGENTS.md` in the repository root, which applies here
+as well.
+
+## Configuration plugins
+
+Plugins can configure:
+- Self-hosted LLM providers
+- Update behavior
+- Preview features visibility
+- Preselected profiles
+- Chat templates
+- etc.
+
+Configuration plugins provide three kinds of values:
+- **Managed settings:** simple values such as booleans, numbers, strings, enums, lists, or sets handled through `ManagedConfiguration`. These values may be locked or used as organization defaults. Which configuration plugin owns a locked setting is persisted in `Data.ManagedLockedConfigurations`, and organization defaults are tracked in `Data.ManagedEditableDefaults`. Both are cleaned up generically by `ManagedConfiguration.CleanupLeftOverManagedConfigurations(...)` when the owning plugin is gone. The value a setting had before a configuration plugin took it over is kept in `Data.ManagedUserValueSnapshots` and restored by that same clean-up, so removing a plugin hands the user's own value back instead of the app default.
+- **Managed configuration objects:** complex Lua tables that are persisted into `SettingsManager.ConfigurationData`, implement `IConfigurationObject`, and are cleaned up through `PluginConfigurationObject.CleanLeftOverConfigurationObjects(...)`. Examples include providers, profiles, chat templates, data sources, and document analysis policies.
+- **Live plugin content:** complex Lua tables that implement `ILivePluginContent` and are read live from running plugins instead of being persisted to `ConfigurationData`. Examples include `MANDATORY_INFOS` and `INTRODUCTIONS`. If live plugin content creates persistent side data, add a dedicated cleanup path for that side data, like mandatory-info acceptances.
+
+When adding configuration plugin capabilities:
+- For managed settings, update the corresponding data class in `app/MindWork AI Studio/Settings/DataModel/` to call `ManagedConfiguration.Register(...)` and process the setting in `PluginConfiguration.TryProcessConfiguration`. Cleaning up the setting when its configuration plugin was removed needs no extra step: `ManagedConfiguration.CleanupLeftOverManagedConfigurations(...)` iterates all registered settings. Do not add per-setting cleanup calls to `PluginFactory.Loading.LoadAll`.
+- For managed configuration objects, update `PluginConfigurationObject.cs` and `PluginConfigurationObjectType.cs`, persist them in the appropriate `ConfigurationData` collection, and add cleanup via `PluginConfigurationObject.CleanLeftOverConfigurationObjects(...)`.
+- For live plugin content, add a data type implementing `ILivePluginContent`, parse it in `PluginConfiguration`, expose it through `PluginFactory`, and add any required cleanup only for persistent side data.
+- Always document the new capability in `app/MindWork AI Studio/Plugins/configuration/plugin.lua`.
@@ -0,0 +1 @@
+@AGENTS.md
@@ -0,0 +1,47 @@
+# AGENTS.md
+
+These instructions cover the indexing pipeline in `app/MindWork AI Studio/Tools/Services/Indexing/` and
+`DataSourceEmbeddingService`. They add to the `AGENTS.md` in the repository root, which applies here as
+well.
+
+## Indexed data sources
+
+The parts:
+- **`IIndexedDataSource`** (`Settings/`) - what indexing needs to know about a data source: confidence level,
+  embedding provider and chunk settings. `IDataSourceBase` is what every data source has. Implement
+  `IDataSource` on top only when classic RAG, Semantic Search and the agents should see the data source. A data
+  source kept in a list of its own implements `IIndexedDataSource` alone, and the compiler keeps it out of
+  `DataSources`.
+- **`IIndexedSourceIndexer`** - one per kind of data source. `Supports` claims the data sources, `ProcessAsync`
+  finds and reads the documents of one run, and `TrackChanges` / `StopTracking` notice changes on their own.
+  `FileSourceIndexer` is the reference: a file system watcher per data source, fingerprints over path, size and
+  write time.
+- **`IndexedRunContext`** - one prepared run: both stores, the embedding provider, the manifest and the
+  collection. `IndexDocumentAsync` embeds and stores one document; the cleanup methods remove what a failed
+  attempt left behind.
+- **`EmbeddingDocument`** - one document: its key, its index row, its display name, and how to read its chunks.
+- **`DocumentRunProgress`** - counts the documents, records indexed and failed ones in the stores, publishes the
+  status and completes the run.
+- **`TextChunker`** - cuts text into chunks the embedding provider accepts. Pick one of its strategies; do not
+  write a chunker of your own.
+
+To add a kind of data source:
+1. Write its indexer in `Tools/Services/Indexing/` and create it in `DataSourceEmbeddingService.CreateIndexers`,
+   which hands every indexer the same `TextChunker`.
+2. Gate it in `IsSupportedIndexedSource`, behind a preview feature of its own while it is new.
+3. When the data source is not kept in `DataSources`, add its list to `GetConfiguredIndexedSources`. Every lookup
+   by id and every pass over all data sources goes through it: the startup hash check,
+   `QueueAllInternalDataSourcesAsync` and `RefreshWatchers`.
+4. Keep whatever the kind has to remember beyond its documents in tables of its own in the index store, added
+   by an EF Core migration (see `app/MindWork AI Studio/Tools/Databases/AGENTS.md`).
+5. Report every status through `DocumentRunProgress`, so all rows of the embedding page behave alike.
+
+Rules which are easy to break:
+- **A document key is not a path.** Only files use their full path as the key. Never pass a key through the
+  `Path` APIs: on Windows, `Path.GetFullPath` reads a key like `mail:…` as a file with an alternate data stream.
+- **Ids and signature are pinned.** The formats in `IndexedDocumentIds` and the embedding signature
+  (`DataSourceEmbeddingService.BuildEmbeddingSignature`) are fixed by tests, because every stored chunk and every
+  index depends on them. When the metadata stored next to a chunk changes, raise `CHUNK_METADATA_VERSION`
+  deliberately: that rebuilds every index.
+- **The service decides when, the indexer decides how.** Whether changes are tracked at all depends on the
+  automatic refresh setting and the startup hash check, and only the embedding service decides that.
@@ -0,0 +1 @@
+@AGENTS.md
@@ -0,0 +1,21 @@
+# AGENTS.md
+
+These instructions cover the tool calling system in `app/MindWork AI Studio/Tools/ToolCallingSystem/`. They
+add to the `AGENTS.md` in the repository root, which applies here as well; its "Tool Calling System"
+section explains how selections name tool collections.
+
+## Tool Calling System
+
+When adding, changing, or removing model-driven tools, keep these parts in sync:
+- `app/MindWork AI Studio/Tools/ToolCallingSystem/ToolCallingImplementations/` for the `IToolImplementation` class, which states its own `ToolDefinition` through `GetDefinition()`, written with `ToolSettingsSchemaBuilder` for its settings and `ToolParameterSchemaBuilder` for the arguments the model passes. There are no tool definition files; a tool arriving from elsewhere brings an `IToolDefinitionSource` instead.
+- `app/MindWork AI Studio/Program.cs` for DI registration of the implementation. Registering it as an `IToolImplementation` is enough, because `CodeToolDefinitionSource` collects the definitions of all of them.
+- An `IToolCollection` next to the tools, registered in `Program.cs`, when tools only make sense together.
+- `app/MindWork AI Studio/Tools/ToolCallingSystem/ToolSelectionRules.cs` when the shared tool-call limits change. A tool's own minimum provider confidence belongs in its definition, or in the definition of its collection, not here.
+- `app/MindWork AI Studio/Tools/ToolCallingSystem/ToolSettingsOptionSources.cs` when a tool setting offers a fixed choice the app maintains, such as languages. Prefer this over spelling the values out in the settings schema; it keeps the list in one place and gives the user translated names.
+- `app/MindWork AI Studio/Plugins/configuration/plugin.lua` to document each setting's field name, meaning, and data type. Tool settings need no code to be centrally manageable: an organization addresses them by `"<toolId>.<fieldName>"` in `DataTools.LockedToolSettings` or `DataTools.DefaultToolSettings`.
+
+Tool implementations must treat model-provided arguments as untrusted input. Validate settings and arguments, protect secrets with `SensitiveTraceArgumentNames`, use `ToolExecutionBlockedException` for intentional policy blocks, and check provider confidence before returning sensitive data to the model.
+
+A tool which belongs to a preview feature returns false from `IToolImplementation.IsAvailable` while the preview is switched off; the registry then leaves it out of every list, every request, and the token count, so no component has to check that preview for the tool. Every tool declares in `IToolImplementation.OutboundData` where its arguments go: a chat which read from a mailbox keeps the tools whose data goes further than the mailbox allows from being offered and from running, see `ToolSelectionRules.IsOutboundDataAllowed`. A tool which brings content of a mailbox into the chat raises `ToolExecutionResult.RequiredOutboundDataRestriction`, next to `RequiredProviderConfidence` and `RequiredDataSecurity`. "Searching Mailboxes" in `documentation/Tools.md` explains the mail tools.
+
+A tool which offers itself from the context of a chat instead of being selected, such as `semantic_search`, sets `Activation = ToolActivation.CONTEXT` and tailors its function to each request in `ResolveFunctionAsync`.
@@ -0,0 +1 @@
+@AGENTS.md