@trace.market/types 0.4.0 → 0.4.1

package/.github/plan-authentiqTypesIntegration.prompt.md

@@ -0,0 +1,154 @@
+## Plan: Authentiq Types Integration
+
+Add marketplace-layer types from src/authentiq.ts into the package in a way that complements, rather than replaces, the existing supply-chain model in src/index.d.ts. Reuse current Price, Facility, Process, ProductInstance, ToolInstance, and KnowHow where possible; add only the missing entity layers and bridge fields needed to map products, services, know-how, and offers.
+
+**Steps**
+1. Keep current supply-chain core in place: ProductInstance, Process, KnowHow, Impact, Facility, Price remain the package foundation.
+2. Add missing marketplace primitives from authentiq.ts: MediaFile, GeoLocation, SocialAccount, Availability, WeeklyTimeSlot, OneTimeDateSlot, ServiceDeliveryModes, plus bounded enums that are not already covered.
+3. Add missing entity hierarchy: ProofOfProvenance, ProofOfProduct, ProofOfService, ProductType, ServiceType, ProductItem, ServiceItem, plus create/update request types only if the package is intended to ship API contracts.
+4. Bridge marketplace entities to supply-chain entities instead of duplicating them: connect ProductType and ServiceType to KnowHow, ToolInstance, Impact, and ProductInstance/Process references.
+5. Normalize overlaps carefully: decide whether Price.currency should become a tighter union, whether GeoLocation should coexist with GeoJSON Point Location, and whether License should be shared by KnowHow and Product/Service offerings.
+6. Extend descriptions metadata for any newly exported public types so MCP graph/editor features can explain them consistently.
+7. Verify with tsc --noEmit and check that public exports remain backward compatible.
+
+**Relevant files**
+- /opt/tm-types/src/index.d.ts — current supply-chain/public type surface to preserve and extend
+- /opt/tm-types/src/authentiq.ts — candidate marketplace/product/service model to integrate
+- /opt/tm-types/src/descriptions.ts — field metadata that should be kept in sync with public types
+- /opt/tm-types/package.json — confirms package entrypoint is src/index.d.ts
+
+**Verification**
+1. Confirm no duplicate/conflicting public names between authentiq.ts and index.d.ts.
+2. Validate that ProductType/ServiceType can reference KnowHow, ToolInstance, and Impact without introducing circular ambiguity.
+3. Run npm run validate in /opt/tm-types.
+
+**Decisions**
+- Include: entity layers needed for provenance, products, services, offers, scheduling, media, and social metadata.
+- Exclude by default: private identity fields in PersonalData and CRUD API interfaces unless this package is intentionally becoming an API contract package.
+- Preferred approach: additive exports plus bridge fields/types, not a rewrite of existing supply-chain types.
+
+I’m comparing the attached Authentiq model against the existing types package so I can identify the minimum fields and structures needed to represent services, products, and know-how cleanly without overloading the current schema.
+
+Compare authentiq to types
+
+Read memory
+
+Read [](file:///opt/tm-types)
+
+Read [](file:///opt/tm-types/src/authentiq.ts#1-1), lines 1 to 300
+
+Read [](file:///opt/tm-types/src)
+
+Read [](file:///opt/tm-types/src/authentiq.ts#300-300), lines 300 to 493
+
+Read [](file:///opt/tm-types/src/index.d.ts)
+
+Read [](file:///opt/tm-types/src/descriptions.ts#1-1), lines 1 to 500
+
+Read [](file:///opt/tm-types/src/openlcaMcpTypes.ts)
+
+Searched for regex `KnowHow|Media|Location|Pricing|Availability|Organization` (`ssh-remote+167.235.250.122` · `opt/tm-types/src/**`), 20 results
+
+Read [](file:///opt/tm-types/src/descriptions.ts#500-500), lines 500 to 759
+
+Created memory file [](file:///root/.vscode-server/data/User/workspaceStorage/ce8095297ecce63c8ebdb28cda4536e1/GitHub.copilot-chat/memory-tool/memories/NTYzZTkxNTAtNjRmYy00NWU1LTkzZmQtNTgxZjNhZjMzNmVm/tm-types-authentiq-analysis.md)
+
+I have the comparison report. Next I’m pulling the current package symbols and the subagent’s findings into a concrete recommendation set so the answer stays tied to what already exists in this repo.
+
+Searching for files matching `ssh-remote+167.235.250.122` · `opt/tm-types/src/*`
+
+Searched for regex `KnowHow|FoodInstance|ProductInstance|Impact|Facility|Location|Price|MachineInstance|Service|Product|provenance` (`ssh-remote+167.235.250.122` · `opt/tm-types/src/**`), 200 results
+
+Read [](file:///root/.vscode-server/data/User/workspaceStorage/ce8095297ecce63c8ebdb28cda4536e1/GitHub.copilot-chat/chat-session-resources/563e9150-64fc-45e5-93fd-581f3af336ef/call_jMNmeQVYFe1zCVZBVBJ7VPrP__vscode-1774861952263/content.txt)
+
+I’ve confirmed the current package already has process, impact, price, facility, and know-how concepts. I’m pulling the exact core type definitions now so the recommendation is limited to what is genuinely missing rather than duplicating what the package already models.
+
+Read [](file:///opt/tm-types/src/index.d.ts#1-1), lines 1 to 260
+
+Read [](file:///opt/tm-types/src/descriptions.ts#440-440), lines 440 to 740
+
+Read [](file:///opt/tm-types/package.json)
+
+I have enough context to make a scoped recommendation. I’m saving a concise integration plan in session memory so the package changes and boundaries are explicit if you want to implement this next.
+
+Created memory file [](file:///root/.vscode-server/data/User/workspaceStorage/ce8095297ecce63c8ebdb28cda4536e1/GitHub.copilot-chat/memory-tool/memories/NTYzZTkxNTAtNjRmYy00NWU1LTkzZmQtNTgxZjNhZjMzNmVm/plan.md)
+
+The current package already covers the supply-chain side well: ProductInstance, Process, Facility, Price, ToolInstance, Impact, and KnowHow are already in src/index.d.ts through src/index.d.ts. What it does not have is the marketplace and provenance hierarchy from the attachment. So the fields to add are mostly the ones that describe who offers something, what is being offered, and how that offer is scheduled or presented.
+
+**What to add**
+Add the missing entity layers from src/authentiq.ts to the public package surface:
+
+- Provenance / org layer from src/authentiq.ts:
+  ProofOfProvenance fields: id, walletAddress, name, keywords, websiteUrl, description, location, logo, peers, intellectualProperty, createdAt, updatedAt
+
+- Product DAO layer from src/authentiq.ts:
+  ProofOfProduct fields: id, walletAddress, provenanceId, name, keywords, websiteUrl, description, location, logo, peers, productTypes, createdAt, updatedAt
+
+- Service DAO layer from src/authentiq.ts:
+  ProofOfService fields: id, walletAddress, provenanceId, name, keywords, websiteUrl, description, location, logo, peers, serviceTypes, createdAt, updatedAt
+
+- Product offer template layer from src/authentiq.ts:
+  ProductType fields: id, walletAddress, productId, name, keywords, license, physicalSpecs, price, currency, openForSpecialRequests, shortDescription, contents, specificDescription, photos, documentProofs, validationCertificates, createdAt, updatedAt
+
+- Service offer template layer from src/authentiq.ts:
+  ServiceType fields: id, walletAddress, serviceId, name, keywords, license, availability, deliveryModes, averageDuration, durationUnit, price, currency, openForSpecialRequests, shortDescription, contents, specificDescription, photos, documentProofs, validationCertificates, createdAt, updatedAt
+
+- Product listing layer from src/authentiq.ts:
+  ProductItem fields: id, walletAddress, productTypeId, providerWalletAddress, relatedPlatforms, category, keywords, quantity, quantityUnit, offerValidFrom, offerValidTo, description, location, photos, createdAt, updatedAt
+
+- Service listing layer from src/authentiq.ts:
+  ServiceItem fields: id, walletAddress, serviceTypeId, providerWalletAddress, relatedPlatforms, category, keywords, occasionsToOffer, offerValidFrom, offerValidTo, description, location, photos, createdAt, updatedAt
+
+**Supporting types you should also add**
+These are the attachment fields that make the above usable and are not already well represented in the package:
+
+- GeoLocation: address, lat, lng from src/authentiq.ts
+- MediaFile: id, url, caption, mimeType, uploadedAt from src/authentiq.ts
+- SocialAccount: platform, handle from src/authentiq.ts
+- Availability: mode, timezone, weekly, onetime from src/authentiq.ts
+- WeeklyTimeSlot: day, startTime, endTime from src/authentiq.ts
+- OneTimeDateSlot: date, startTime, endTime from src/authentiq.ts
+- ServiceDeliveryModes: online, inPerson, onSite from src/authentiq.ts
+- ProductPhysicalSpecs: dimensions, dimensionsUnit, weight, weightUnit, netVolume, volumeUnit, packagingQuantity, packagingType from src/authentiq.ts
+- IntellectualProperty: license, description, photos, documentProofs, validationCertificates from src/authentiq.ts
+
+**What to map, not duplicate**
+A few attachment concepts overlap with the existing package and should be bridged instead of copied blindly:
+
+- Know-how: keep the existing KnowHow from src/index.d.ts, then let ProductType and ServiceType reference it.
+- Price: the package already has Price in src/index.d.ts. I would extend or normalize that rather than introducing a second price shape.
+- Location: the package uses GeoJSON Point as Location in src/index.d.ts, while Authentiq uses GeoLocation with address plus lat/lng. Keep both only if you need both map precision and human-readable address; otherwise define one canonical location model and adapters.
+- Impact and ToolInstance already exist in src/index.d.ts and src/index.d.ts. ProductType and ServiceType should reference these rather than re-declare similar fields.
+
+**What I would not add by default**
+These are valid in the attachment, but I would keep them out of the core types package unless you explicitly want this package to become an API-contract and identity package:
+
+- PersonalData from src/authentiq.ts, especially bankAccountIban, identityCardNumber, passportNumber, ssn, biometricProofs, medicalRecords
+- CRUD API interfaces from src/authentiq.ts
+- Create and update request types, unless this package is meant to ship request/response DTOs as part of the public contract
+
+**Recommended minimal set**
+If you want the smallest useful addition for mapping services, products, and know-how, add only:
+
+1. ProofOfProvenance
+2. ProofOfProduct
+3. ProofOfService
+4. ProductType
+5. ServiceType
+6. ProductItem
+7. ServiceItem
+8. GeoLocation
+9. MediaFile
+10. Availability, WeeklyTimeSlot, OneTimeDateSlot
+11. ServiceDeliveryModes
+12. ProductPhysicalSpecs
+13. IntellectualProperty
+
+Then add bridge references so ProductType and ServiceType can point to existing KnowHow, ToolInstance, Impact, and optionally ProductInstance or Process.
+
+**Plan**
+I saved a scoped integration plan in session memory at /memories/session/plan.md. The core recommendation is additive: keep the existing supply-chain model in src/index.d.ts, export the marketplace hierarchy from src/authentiq.ts, and connect the two with a few reference fields instead of rewriting the current model.
+
+If you want, the next step can be either:
+1. I draft the exact merged public type surface for src/index.d.ts
+2. I propose the bridge fields between ProductType or ServiceType and KnowHow or Process before any code changes

package/.github/workflows/build-mcp.yml

@@ -19,7 +19,7 @@ jobs:
       
       - uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '24'
       
       - name: Install dependencies
         working-directory: ./mcp-server

package/.github/workflows/publish.yml

@@ -24,7 +24,7 @@ jobs:
       
       - uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '24'
           registry-url: 'https://registry.npmjs.org'
       
       - name: Install dependencies
@@ -33,40 +33,37 @@ jobs:
       - name: Validate types
         run: npm run validate
       
-      - name: Check if version changed
-        id: check
+      - name: Auto-bump patch if version already published
         run: |
           git fetch --tags
+          git config user.name "GitHub Actions"
+          git config user.email "actions@github.com"
           CURRENT_VERSION=$(node -p "require('./package.json').version")
-          if git rev-parse "v$CURRENT_VERSION" >/dev/null 2>&1; then
-            echo "Version $CURRENT_VERSION already exists"
-            echo "changed=false" >> $GITHUB_OUTPUT
-          else
-            echo "New version $CURRENT_VERSION"
-            echo "changed=true" >> $GITHUB_OUTPUT
-            echo "version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
-          fi
-      
+          while git rev-parse "v$CURRENT_VERSION" >/dev/null 2>&1; do
+            echo "Tag v$CURRENT_VERSION already exists – bumping patch"
+            npm version patch --no-git-tag-version
+            CURRENT_VERSION=$(node -p "require('./package.json').version")
+          done
+          echo "Publishing as v$CURRENT_VERSION"
+          echo "version=$CURRENT_VERSION" >> $GITHUB_ENV
+          git add package.json
+          git commit -m "chore: auto-bump to v$CURRENT_VERSION [skip ci]" || true
+
       - name: Publish to NPM
-        if: steps.check.outputs.changed == 'true'
         run: npm publish --provenance --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-      
-      - name: Create Git tag
-        if: steps.check.outputs.changed == 'true'
+
+      - name: Create Git tag and push
         run: |
-          git config user.name "GitHub Actions"
-          git config user.email "actions@github.com"
-          git tag "v${{ steps.check.outputs.version }}"
-          git push origin "v${{ steps.check.outputs.version }}"
-      
+          git tag "v${{ env.version }}"
+          git push origin HEAD:main "v${{ env.version }}"
+
       - name: Create GitHub Release
-        if: steps.check.outputs.changed == 'true'
-        uses: softprops/action-gh-release@v1
+        uses: softprops/action-gh-release@v2
         with:
-          tag_name: v${{ steps.check.outputs.version }}
-          name: Release v${{ steps.check.outputs.version }}
+          tag_name: v${{ env.version }}
+          name: Release v${{ env.version }}
           draft: false
           prerelease: false
         env:

package/CHANGELOG.md

@@ -9,8 +9,7 @@ All notable changes to this project will be documented in this file.
 
 ### Features
 - **Process Types**: Added `PyrolysisProcess` and `DistillationProcess`.
-- **ToolInstance**: Added `specs` (flexible map for capacity, material, etc.) and `components` (nested tools) to support complex equipment hierarchies like pyrolysis reactors.
-- **Process**: Added `parameters` to `GenericProcess` for capturing real-time or run-specific data (pressure, speed, etc.).
+- **Process**: Added `notes` to `GenericProcess` for capturing real-time or run-specific data (pressure, speed, etc.).
 - **Icons**: Added icons for new processes (`local_fire_department` for Pyrolysis, `science` for Distillation).
 
 ## [0.3.0] - 2026-01-19

package/field-capabilities.csv

@@ -0,0 +1,108 @@
+field,parent,category,type,labels
+errorMessage,FetchError,support,string,supply-chain tracking
+notes,Pokedex,support,string,"supply-chain tracking, selling it online"
+roles,Pokedex,support,string,supply-chain tracking
+token,Pokedex,support,string,supply-chain tracking
+typesVersion,Pokedex,support,string,selling it online
+instance,Pokedex,support,ProductInstance,supply-chain tracking
+label,Facility,support,string,supply-chain tracking
+location,Facility,support,Location,supply-chain tracking
+timestamp,GenericProcess,process,number,"estimate carbon footprint, supply-chain tracking"
+duration,GenericProcess,process,number,estimate carbon footprint
+facility,GenericProcess,process,Facility,"estimate carbon footprint, supply-chain tracking"
+temperatureRange,GenericProcess,process,TemperatureRange,estimate carbon footprint
+inputInstances,GenericProcess,process,(TransportedInputInstance | LocalInputInstance)[],"estimate carbon footprint, supply-chain tracking"
+impacts,GenericProcess,process,Impact[],estimate carbon footprint
+price,GenericProcess,process,Price,selling it online
+hr,GenericProcess,process,Hr,"estimate carbon footprint, supply-chain tracking"
+notes,GenericProcess,process,"Record<string, string | number | boolean>","supply-chain tracking, selling it online"
+type,PrintingProcess,process,"""printing""",selling it online
+toolInstance,PrintingProcess,process,TokenIdOr<ToolInstance>,"estimate carbon footprint, supply-chain tracking"
+knowHow,PrintingProcess,process,TokenIdOr<KnowHow>,supply-chain tracking
+shape,PrintingProcess,process,string /* URL */,"estimate carbon footprint, supply-chain tracking"
+type,MillingProcess,process,"""milling""",selling it online
+knowHow,MillingProcess,process,TokenIdOr<KnowHow>,supply-chain tracking
+toolInstance,MillingProcess,process,TokenIdOr<ToolInstance>,"estimate carbon footprint, supply-chain tracking"
+type,FreezeDryingProcess,process,"""freezedrying""",selling it online
+knowHow,FreezeDryingProcess,process,TokenIdOr<KnowHow>,supply-chain tracking
+toolInstance,FreezeDryingProcess,process,TokenIdOr<ToolInstance>,"estimate carbon footprint, supply-chain tracking"
+type,BlendingProcess,process,"""blending""",selling it online
+toolInstance,BlendingProcess,process,TokenIdOr<ToolInstance>,"estimate carbon footprint, supply-chain tracking"
+knowHow,BlendingProcess,process,TokenIdOr<KnowHow>,supply-chain tracking
+type,SaleProcess,process,"""sale""",selling it online
+price,SaleProcess,process,Price,selling it online
+type,HarvestProcess,process,"""harvest""",selling it online
+type,CookingProcess,process,"""cooking""",selling it online
+method,CookingProcess,process,"""baking"" | ""boiling"" | ""frying"" | ""steaming"" | ""roasting"" | ""sous-vide"" | ""grilling""","estimate carbon footprint, supply-chain tracking"
+toolInstance,CookingProcess,process,TokenIdOr<ToolInstance>,"estimate carbon footprint, supply-chain tracking"
+knowHow,CookingProcess,process,TokenIdOr<KnowHow>,supply-chain tracking
+type,PyrolysisProcess,process,"""pyrolysis""",selling it online
+toolInstance,PyrolysisProcess,process,TokenIdOr<ToolInstance>,"estimate carbon footprint, supply-chain tracking"
+knowHow,PyrolysisProcess,process,TokenIdOr<KnowHow>,supply-chain tracking
+type,DistillationProcess,process,"""distillation""",selling it online
+toolInstance,DistillationProcess,process,TokenIdOr<ToolInstance>,"estimate carbon footprint, supply-chain tracking"
+knowHow,DistillationProcess,process,TokenIdOr<KnowHow>,supply-chain tracking
+amount,Price,support,number,supply-chain tracking
+currency,Price,support,string,supply-chain tracking
+type,Price,support,"""budget"" | ""is"" | ""%"" | ""payin30days"" | ""payin60days""",selling it online
+instance,GenericInputInstance,product,TokenIdOr<ProductInstance>,supply-chain tracking
+quantity,GenericInputInstance,product,number,estimate carbon footprint
+type,LocalInputInstance,product,"""local""",selling it online
+type,TransportedInputInstance,product,"""transported""","estimate carbon footprint, supply-chain tracking, selling it online"
+transport,TransportedInputInstance,product,Transport,"estimate carbon footprint, supply-chain tracking"
+method,Transport,support,TransportMethod,"estimate carbon footprint, supply-chain tracking"
+fuelType,Transport,support,"""hydrogen"" | ""electric"" | ""diesel"" | ""petrol"" | ""kerosene""","estimate carbon footprint, selling it online"
+weight,Transport,support,number,estimate carbon footprint
+deparetureTime,Transport,support,number,supply-chain tracking
+duration,Transport,support,number,estimate carbon footprint
+type,ProductInstanceBase,product,string,selling it online
+ownerId,ProductInstanceBase,product,string,supply-chain tracking
+expiryDate,ProductInstanceBase,product,number,"selling it online, supply-chain tracking"
+bio,ProductInstanceBase,product,boolean,"selling it online, supply-chain tracking"
+quantity,ProductInstanceBase,product,number,estimate carbon footprint
+price,ProductInstanceBase,product,Price,selling it online
+title,ProductInstanceBase,product,string,selling it online
+notes,ProductInstanceBase,product,string,"supply-chain tracking, selling it online"
+pictureURL,ProductInstanceBase,product,string,selling it online
+category,FoodInstance,product,"""food""","supply-chain tracking, selling it online"
+iDs,FoodInstance,product,ID[],supply-chain tracking
+nutrients,FoodInstance,product,FallbackFoodNutrient[],"selling it online, supply-chain tracking"
+format,FoodInstance,product,string,selling it online
+grade,FoodInstance,product,string,selling it online
+size,FoodInstance,product,string,selling it online
+process,FoodInstance,product,Process,"estimate carbon footprint, supply-chain tracking"
+labels,FoodInstance,product,string[],selling it online
+category,NonFoodInstance,product,"""non-food""","supply-chain tracking, selling it online"
+grade,NonFoodInstance,product,string,selling it online
+size,NonFoodInstance,product,string,selling it online
+labels,NonFoodInstance,product,string[],selling it online
+category,PackagingInstance,product,"""packaging""","supply-chain tracking, selling it online"
+material,PackagingInstance,product,string,"selling it online, supply-chain tracking"
+labels,PackagingInstance,product,string[],selling it online
+amount,FallbackFoodNutrient,product,number,"selling it online, supply-chain tracking"
+iD,FallbackFoodNutrient,product,ID,supply-chain tracking
+category,ToolInstance,product,string,"supply-chain tracking, selling it online"
+ownerId,ToolInstance,product,string,supply-chain tracking
+quantity,ToolInstance,product,number,estimate carbon footprint
+size,ToolInstance,product,string,selling it online
+ratedPowerKW,ToolInstance,product,number,estimate carbon footprint
+providerSDomain,ToolInstance,product,string,supply-chain tracking
+hash,ToolInstance,product,string,supply-chain tracking
+tasks,Hr,support,string[],supply-chain tracking
+assignee,Hr,support,string,supply-chain tracking
+min,TemperatureRange,support,number,supply-chain tracking
+max,TemperatureRange,support,number,supply-chain tracking
+owner,KnowHow,support,string,supply-chain tracking
+hash,KnowHow,support,string,supply-chain tracking
+inputs,KnowHow,support,string,"estimate carbon footprint, supply-chain tracking"
+outputs,KnowHow,support,string | object,supply-chain tracking
+licenseFee,KnowHow,support,Price,"supply-chain tracking, selling it online"
+note,KnowHow,support,string | object,supply-chain tracking
+logoURL,KnowHow,support,string,selling it online
+ownerId,GenericImpact,impact,string,supply-chain tracking
+format,GenericImpact,impact,string,selling it online
+quantity,GenericImpact,impact,number,estimate carbon footprint
+category,CarbonImpact,impact,"""carbon""","estimate carbon footprint, supply-chain tracking, selling it online"
+category,WaterImpact,impact,"""water""","estimate carbon footprint, supply-chain tracking, selling it online"
+registry,ID,support,string,supply-chain tracking
+id,ID,support,string,supply-chain tracking

package/mcp-server/agents-usage-prompt.md

@@ -0,0 +1,100 @@
+# TM Types Usage Audit Prompt
+
+Use this prompt with each agent/team who owns a microservice or module.
+
+---
+
+## Goal
+Identify which `tm-types` are used by each microservice/module **and** what each service/module can do so we can:
+- **Containerize** them logically
+- **Reduce redundancy** (overlaps)
+- Plan roadmap from **current** to **target** usage
+- Monetize each container as APIs/SDKs/GUIs
+
+---
+
+## Please return the following JSON
+
+```json
+{
+  "service": {
+    "name": "<service name>",
+    "status": "current | target",
+    "description": "<what this service does>",
+    "features": {
+      "gui": ["<feature exposed in UI>", "..."],
+      "api": ["<feature exposed programmatically>", "..."],
+      "mcp": ["<feature exposed via MCP>", "..."]
+    },
+    "modules": [
+      {
+        "name": "<module name>",
+        "status": "current | target",
+        "description": "<module purpose>",
+        "features": {
+          "gui": ["<feature exposed in UI>", "..."],
+          "api": ["<feature exposed programmatically>", "..."],
+          "mcp": ["<feature exposed via MCP>", "..."]
+        },
+        "types": [
+          "<tm-type-1>",
+          "<tm-type-2>",
+          "..."
+        ]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Guidance
+- **List every `tm-type`** your module uses (interfaces or types).
+- **List features** for both GUI and programmatic surfaces (API/SDK/MCP).
+- Mark **status** as `current` for today’s usage and `target` for your ideal future usage.
+- If a module is planned but not live, still list it as `target`.
+- If unsure about a type name, include your best guess and a note.
+
+---
+
+## Examples
+
+```json
+{
+  "service": {
+    "name": "Pricing Service",
+    "status": "current",
+    "description": "Calculates price quotes and promotions",
+    "features": {
+      "gui": ["Quote preview", "Promo simulator"],
+      "api": ["Quote calculation", "Discount eligibility"],
+      "mcp": ["Quote intent", "Promotion suggestion"]
+    },
+    "modules": [
+      {
+        "name": "Quote Engine",
+        "status": "current",
+        "description": "Builds live quotes from inputs",
+        "features": {
+          "gui": ["Live quote panel"],
+          "api": ["/quotes/preview"],
+          "mcp": ["quote.generate"]
+        },
+        "types": ["Price", "Money", "Discount", "ProductInstance"]
+      },
+      {
+        "name": "Promo Simulator",
+        "status": "target",
+        "description": "What-if promo analysis",
+        "features": {
+          "gui": ["Scenario builder"],
+          "api": ["/promos/simulate"],
+          "mcp": ["promo.simulate"]
+        },
+        "types": ["Price", "Promotion", "Scenario"]
+      }
+    ]
+  }
+}
+```