updates for agents

Author: eigenverft

src/prj/Eigenverft.Manifested.Package.Test/Eigenverft.Manifested.Package.Package.ExportsAndState.Tests.ps1

@@ -178,6 +178,8 @@ Invoke-TestPackageDescribe -Name 'Eigenverft.Manifested.Package Package - export
             'Before making any JSON edit',
             'eigenverft-module-package-definition-1.9.schema.json',
             'x-eigenverftAgentHint',
+            'nested `description` and `$comment` fields',
+            'Treat schema `description` and `$comment` text as authoring instructions',
             'Do not skim',
             'Start Here',
             'Runtime endpoint status',
@@ -206,6 +208,8 @@ Invoke-TestPackageDescribe -Name 'Eigenverft.Manifested.Package Package - export
             'git status --short',
             'validation, signing, and trust verification',
             'Test-PackageDefinitionCatalog',
+            'raw JSON Schema validation',
+            'Test-Json',
             'Get-PackageSigningProfile',
             'Sign-PackageDefinition',
             'Resign-PackageDefinition',
@@ -215,6 +219,7 @@ Invoke-TestPackageDescribe -Name 'Eigenverft.Manifested.Package Package - export
             'Agent Completion At A Valid Endpoint',
             'definitionSignature.kind = unsigned',
             'signatureValue',
+            'installerKind` is descriptive metadata',
             '.cer',
             '.pem'
         )

src/prj/Eigenverft.Manifested.Package/AgentSkills/PackageDefinitionAuthoring.md

@@ -41,11 +41,11 @@ Before making any JSON edit, ground the work in the user's task, the prepended r
 
 **Read fully (required):**
 
-- The prepended **Task**, **Authoring mode**, and **Runtime endpoint status** (when present), plus this guide
-- `Schema/PackageDefinition/eigenverft-module-package-definition-1.9.schema.json` on the machine where the module is installed. Resolve the folder with `(Get-Module Eigenverft.Manifested.Package).ModuleBase` after import, or `Get-Module -ListAvailable Eigenverft.Manifested.Package` if import fails. Read the complete schema, including the root `description` and `x-eigenverftAgentHint`.
+- The prepended **Task**, **Authoring mode**, and **Runtime endpoint status** (when present), plus this guide from top to bottom.
+- `Schema/PackageDefinition/eigenverft-module-package-definition-1.9.schema.json` on the machine where the module is installed. Resolve the folder with `(Get-Module Eigenverft.Manifested.Package).ModuleBase` after import, or `Get-Module -ListAvailable Eigenverft.Manifested.Package` if import fails. Read the complete schema, including the root `description`, `x-eigenverftAgentHint`, and the relevant nested `description` and `$comment` fields for every object shape you edit.
 - Any extra instructions the user gave in chat (publisher, scope, installer kind, draft vs signed, and so on)
 
-For normal authoring, these inputs are enough: the skill explains workflow, endpoints, validation, and signing; the schema defines shape, acquisition, dependencies, and materialization. Follow the schema first.
+For normal authoring, these inputs are enough: the skill explains workflow, endpoints, validation, and signing; the schema defines shape, acquisition, dependencies, and materialization. Follow the schema first. Treat schema `description` and `$comment` text as authoring instructions, not decoration.
 
 **Read only when needed:**
 
@@ -57,7 +57,9 @@ For normal authoring, these inputs are enough: the skill explains workflow, endp
 
 - PowerShell module source, engine implementation, dependency planner, trust model, or installer runtime code. Authoring is declarative JSON work.
 
-Do not skim the required inputs or infer missing rules from example JSON alone. If the user's task, schema, and an example disagree - or if the schema cannot be read fully - stop and ask the user before editing.
+Do not skim the required inputs or infer missing rules from example JSON alone. If the user's task, this guide, schema comments/descriptions, and an example disagree - or if this guide or the schema cannot be read fully - stop and ask the user before editing.
+
+Every property you write must be allowed by the JSON Schema for the selected object shape. Do not add "helpful" extra properties because they seem useful to the engine or appear in a guessed installer command. If the schema cannot express the package behavior, stop and report the schema/authoring mismatch instead of forcing JSON through a looser validator.
 
 ## Authoring Targets And Endpoints
 
@@ -226,6 +228,8 @@ When the installer kind, silent arguments, extraction behavior, or package forma
 
 Discover whether the vendor ships multiple artifact kinds for the same product, such as portable archives, user installers, machine/admin installers, MSI packages, app-store packages, or architecture-specific builds. Prefer a vendor-published portable archive when it fits the package intent. Otherwise prefer a user-scoped installer over a machine/admin installer. Use admin or machine-wide installers only when the user's intent and documentation explicitly require that scope - not because an elevated trial install was run.
 
+Choose the install operation shape from the schema, not from a guessed product-specific label. Prefer the dedicated schema adapters when they fit (`nsisInstaller`, `innoSetupInstaller`, `msiInstaller`, `powershellModuleInstaller`, `expandArchive`, and so on). Use generic `runInstaller` only when the schema's `assignRunInstaller` shape exactly fits the package. `runInstaller.installerKind` is descriptive metadata for logging; it does not create a new adapter and it does not permit extra properties outside the schema. If a custom installer needs a target-directory property that the selected schema shape does not allow, stop and ask for a schema/runtime decision instead of adding an unsupported property.
+
 Do not mix artifact kinds by accident. If the existing definition is for a user installer, update from the user-installer source. If it is for a portable/runtime package, update from the matching portable/runtime source. If intent is unclear, stop and ask the user before switching installer kind.
 
 Non-executing inspection of a downloaded file (for example format identification from headers or static metadata) is a last resort after documentation and examples, and must not launch or install the payload. If the installer format or silent switches still cannot be established confidently, stop and ask the user instead of guessing or installing.
@@ -256,6 +260,7 @@ Stop if the latest version cannot be proven from official sources, an artifact f
 - Dependencies use `dependency.requires[]`.
 - Coexistence policy uses `dependency.policy.conflictsWith[]` or `dependency.policy.requiresAbsent[]` only when the user's intent is explicit.
 - Download URLs, checksums, installer arguments, and materialization paths are reviewable.
+- `packageOperations.assigned.install` uses one exact schema-defined operation shape; no extra fields are added to make a custom installer work.
 - No credentials, tokens, local private paths, or machine-specific secrets are embedded.
 - `definitionSignature.kind` is `unsigned` only while drafting or when explicitly requested.
 
@@ -275,6 +280,16 @@ Test-PackageDefinitionCatalog -Path '<endpoint-root>' -RequireTrusted -ErrorOnFa
 
 Treat validation issues as blockers until the user says otherwise. Do not use `Verify-PackageDefinitionCatalog` as a replacement for schema and reference validation; it checks signature and trust summary, while `Test-PackageDefinitionCatalog` checks parse, schema, signature/trust status, duplicate identities, and static dependency references.
 
+Also run raw JSON Schema validation when the current host supports `Test-Json`; PowerShell 7 usually does. This catches schema-shape errors before signing:
+
+```powershell
+$moduleBase = (Get-Module Eigenverft.Manifested.Package).ModuleBase
+$schemaPath = Join-Path $moduleBase 'Schema\PackageDefinition\eigenverft-module-package-definition-1.9.schema.json'
+Test-Json -Json (Get-Content -Raw -LiteralPath '<definition.json>') -Schema (Get-Content -Raw -LiteralPath $schemaPath) -ErrorAction Stop
+```
+
+If `Test-Json` is unavailable in the current shell, try the other PowerShell host described in **PowerShell Host Check**. If raw schema validation cannot be run, say so in the handoff; do not claim that schema-file validation passed. If `Test-PackageDefinitionCatalog` passes but raw schema validation fails, treat the raw schema failure as a blocker and fix the JSON or ask for a schema/runtime decision.
+
 ## Signing And Signing-Profile Discovery
 
 Use `Sign-PackageDefinition` for first signing and `Resign-PackageDefinition` for changed signed definitions. Use `-KeepSchemaVersion` when re-signing a stable schema version.
@@ -322,9 +337,10 @@ When **Runtime endpoint status** shows `Selection` with status `Ready`:
 
 1. Write the JSON under the **Selection** path (`definitionId` usually from the **Task** line). Prefer `<publisherId>\<definitionId>.json`; use `<definitionId>.json` directly under **Selection** when that matches the endpoint convention or user instruction.
 2. Run `Test-PackageDefinitionCatalog` on that file.
-3. Unless **Authoring mode** is `draft-only`, complete **Publication finalization** (sign with an approved profile when appropriate, then verify signature and trust).
+3. Run raw JSON Schema validation with `Test-Json` when available, or state clearly that raw schema validation could not be run.
+4. Unless **Authoring mode** is `draft-only`, complete **Publication finalization** (sign with an approved profile when appropriate, then verify signature and trust).
 
-Success means the JSON exists on the catalog root with validation (and signing/trust when required). Proof is catalog commands - not installing the product.
+Success means the JSON exists on the catalog root with catalog validation, raw schema validation when available, and signing/trust when required. Proof is validation/signature output - not installing the product.
 
 **Draft-only:** when **Authoring mode** shows `draft-only`, stop after unsigned JSON and schema validation; skip signing and `-RequireTrusted` steps.
 

src/prj/Eigenverft.Manifested.Package/Schema/PackageDefinition/eigenverft-module-package-definition-1.9.schema.json

@@ -4,7 +4,7 @@
   "title": "Eigenverft module package definition document (wire format 1.9)",
   "$comment": "META: JSON Schema for INSTANCE package-definition documents (one file per definition). Runtime validates with DefinitionSchema.ps1 + DefinitionSchema.Wire1_9.ps1, signature assertions, and 1.9 acquisition vocabulary assertions. definitionPublication.definitionSignature is required; kind=unsigned is valid for draft authoring, kind=signed after Sign-PackageDefinition. Endpoints are discovery-only. Recommended layout under an endpoint root: <publisherId>/<definitionId>.json.",
   "description": "AUTHOR TASK - Produce or edit one complete package-definition JSON object for Eigenverft.Manifested.Package. Required top-level order: schemaVersion, definitionPublication, display, dependency, artifacts, discovery, packageOperations. Use schemaVersion exactly 1.9.\n\nAUTHORING VS SIGNING: Design semantic package content first (dependency, artifacts, discovery, packageOperations). A valid embedded signature is not required while drafting. Always include definitionPublication.definitionSignature: for drafts use kind=unsigned with format and signedContent only; do not invent keyThumbprint, signedAtUtc, certificatePem, or signatureValue. Never hand-edit signatureValue base64. After the JSON content is final, signing is a separate maintainer step.\n\nSIGNING WORKFLOW: If no catalog-signing certificate exists, run New-PackageSigningCertificate (creates a password-protected PFX, public CER, and adjacent DPAPI password descriptor; keep the private key off endpoints). Prefer friendly metadata fields such as -CommonName, -Organization, -OrganizationalUnit, -Country, and -SignerDisplayName over raw -Subject unless advanced X.509 control is required. Inject or refresh the embedded signature with Sign-PackageDefinition -Path <file> -Cert <friendly-name-or-pfx> -KeepSchemaVersion and optionally -Password <secure> for CI. Sign-PackageDefinition embeds the public certificate so clients can verify before trusting. Verify with Verify-PackageDefinitionSignature or Verify-PackageDefinitionCatalog before replacing published copies. Admins can preseed public trust with the CER via Import-PackageTrust or Trust-PackageSigningCertificate. Re-run Sign-PackageDefinition after any meaningful definition change and bump definitionRevision.\n\nDEPLOYMENT (neutral): Whether an embedded signature is required depends on client catalogTrust.policy and how trust is delivered-not on this schema alone. Synced file-share or NAS endpoint roots used with strict policy need kind=signed definitions and either trusted keys in PackageTrustInventory.json or a valid embedded certificate that local policy allows the user to trust. Unsigned catalogs may run only where catalogTrust.policy=allowUnsigned and publisher policy explicitly allows unsigned definitions.\n\nPUBLICATION: definitionPublication.publisherId is the maintainer namespace (shipped: Eigenverft; teams: e.g. My Team). definitionPublication.definitionId is the id used by Invoke-Package. Increment definitionPublication.definitionRevision for every meaningful JSON change. publishedAtUtc is audit metadata only.\n\nCATALOG TRUST: Production strict clients expect kind=signed with RSA/SHA-256 signatureValue over canonical JSON excluding signatureValue. certificatePem is public verification material, not a trust decision. kind=unsigned is explicit draft/migration shape and does not prove authorship under strict policy.\n\nDEPENDENCY: dependency is required. dependency.requires is required but may be []. dependency.policy is optional and contains peer policy such as conflictsWith and requiresAbsent. dependency.requires[].publisherId is optional.\n\nCOMMON TRAPS: root repositoryId and root definitionId are retired; top-level dependencies and dependencyPolicy are retired in 1.9; vendorDownload candidates need sourceId+sourcePath or direct url/urlTemplate; GitHub release sources need real assets and releaseTag; packageDepot is the only prepared artifact acquisition candidate; package-definition filesystem acquisition is retired; NSIS and Inno Setup differ; choose package-managed shims vs installer PATH deliberately.",
-  "x-eigenverftAgentHint": "LLM/agent: edit INSTANCE JSON conforming to this schema and DefinitionSchema.Wire1_9.ps1 plus 1.9 signature rules. Author drafts with definitionPublication.definitionSignature.kind=unsigned (no signatureValue). Do not fabricate signatures. After content is stable, a human or automation runs Sign-PackageDefinition -KeepSchemaVersion or Resign-PackageDefinition -KeepSchemaVersion; use New-PackageSigningCertificate when no key exists yet. Shipped examples: Endpoint/Defaults/Eigenverft (signed). Layout: <publisherId>/<definitionId>.json under endpoint roots. Bump definitionRevision on every definition change. Embedded signatures are required for strict file-based catalogs; web or centrally trusted endpoints may use other trust delivery-check deployment policy before assuming unsigned JSON is runnable.",
+  "x-eigenverftAgentHint": "LLM/agent: first read the complete PackageDefinitionAuthoring guide that delivered this task, then read this complete schema. Treat root description, this hint, nested description fields, and $comment fields as authoring requirements. Edit INSTANCE JSON conforming to this schema and DefinitionSchema.Wire1_9.ps1 plus 1.9 signature rules. Author drafts with definitionPublication.definitionSignature.kind=unsigned (no signatureValue). Do not fabricate signatures. After content is stable, a human or automation runs Sign-PackageDefinition -KeepSchemaVersion or Resign-PackageDefinition -KeepSchemaVersion; use New-PackageSigningCertificate when no key exists yet. Shipped examples: Endpoint/Defaults/Eigenverft (signed). Layout: <publisherId>/<definitionId>.json under endpoint roots. Bump definitionRevision on every definition change. Embedded signatures are required for strict file-based catalogs; web or centrally trusted endpoints may use other trust delivery-check deployment policy before assuming unsigned JSON is runnable. Raw JSON Schema validation must pass; do not add extra properties that only a looser runtime validator accepts.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -1278,7 +1278,7 @@
     },
     "packageOperations": {
       "type": "object",
-      "$comment": "AUTHOR FOCUS: assigned chooses install engine (expandArchive, npmMaterializedInstallGlobalPackage, powershellModuleInstaller, nsisInstaller, innoSetupInstaller, msiInstaller, runInstaller, placePackageFile) and must agree with discovery.presence. removed must undo ownership safely (inventory row, shims, delete directory or installer uninstaller). policy sets compatibility and ownership rules before install.",
+      "$comment": "AUTHOR FOCUS: assigned chooses exactly one schema-defined install engine (expandArchive, npmMaterializedInstallGlobalPackage, powershellModuleInstaller, nsisInstaller, innoSetupInstaller, msiInstaller, runInstaller, placePackageFile) and must agree with discovery.presence. Do not mix fields from another install shape; additionalProperties=false is intentional. Use dedicated adapters for NSIS, Inno Setup, and MSI when their target-directory handling fits. Generic runInstaller is only a raw process launch shape and does not allow installDirectory. removed must undo ownership safely (inventory row, shims, delete directory or installer uninstaller). policy sets compatibility and ownership rules before install.",
       "additionalProperties": false,
       "required": [
         "policy",
@@ -1640,6 +1640,7 @@
     "assignRunInstaller": {
       "type": "object",
       "additionalProperties": false,
+      "$comment": "Generic raw installer process launch. This shape intentionally does not own installDirectory. Do not add installDirectory or target-directory helper fields here; choose nsisInstaller, innoSetupInstaller, msiInstaller, expandArchive, or another schema-defined operation when the engine must manage an install directory. installerKind is descriptive/logging metadata only and does not create product-specific behavior.",
       "required": [
         "kind",
         "targetKind",
@@ -1657,13 +1658,15 @@
         },
         "targetKind": {
           "type": "string",
+          "description": "directory means the launched installer is expected to place payload under its own documented arguments, but this shape does not accept installDirectory. machinePrerequisite is for prerequisite installers where readiness can skip acquisition/install when already satisfied.",
           "enum": [
             "directory",
             "machinePrerequisite"
           ]
         },
         "installerKind": {
-          "type": "string"
+          "type": "string",
+          "description": "Descriptive/logging label such as burn. It is not an adapter selector and does not permit properties outside assignRunInstaller."
         },
         "uiMode": {
           "type": "string"