{"id":50166159,"url":"https://github.com/softwareone-platform/mpt-marketplace-canon","last_synced_at":"2026-05-24T21:02:56.724Z","repository":{"id":349496850,"uuid":"1181527319","full_name":"softwareone-platform/mpt-marketplace-canon","owner":"softwareone-platform","description":"The definitive reference for the SoftwareOne Marketplace platform — objects, state machines, business rules, and API behaviours. Essential reading for Vendor, Operations, and Client integrations.","archived":false,"fork":false,"pushed_at":"2026-05-21T13:19:48.000Z","size":644,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-21T22:07:08.261Z","etag":null,"topics":["knowledge-base","marketplace","product-canon","product-management"],"latest_commit_sha":null,"homepage":"https://docs.platform.softwareone.com/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/softwareone-platform.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-14T09:03:56.000Z","updated_at":"2026-05-20T15:11:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/softwareone-platform/mpt-marketplace-canon","commit_stats":null,"previous_names":["softwareone-platform/mpt-marketplace-canon"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/softwareone-platform/mpt-marketplace-canon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softwareone-platform%2Fmpt-marketplace-canon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softwareone-platform%2Fmpt-marketplace-canon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softwareone-platform%2Fmpt-marketplace-canon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softwareone-platform%2Fmpt-marketplace-canon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/softwareone-platform","download_url":"https://codeload.github.com/softwareone-platform/mpt-marketplace-canon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softwareone-platform%2Fmpt-marketplace-canon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33450403,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-24T19:21:36.376Z","status":"ssl_error","status_checked_at":"2026-05-24T19:21:10.562Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["knowledge-base","marketplace","product-canon","product-management"],"created_at":"2026-05-24T21:02:52.584Z","updated_at":"2026-05-24T21:02:56.713Z","avatar_url":"https://github.com/softwareone-platform.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SoftwareOne Marketplace Canon\n\nAuthoritative product canon for the SoftwareOne Marketplace platform. Covers platform invariants, object lifecycles, state machines, business rules, and system behaviour. Built and maintained by the Marketplace product team as a structured reference for engineering, support, and onboarding.\n\n---\n\n## What is Canon?\n\n\u003e **canon** _(n.)_ — a collection of rules, principles, or works officially recognised as authoritative within a given domain.\n\nCanon is the versioned knowledge base for the SoftwareOne Marketplace platform. It is a structured record of every platform object's identity, behaviour, business rules, and lifecycle — so that product decisions are made from a shared, reliable understanding of how the platform actually works, rather than from tribal knowledge or assumption.\n\n---\n\n## Repository Structure\n\n```\nmpt-marketplace-canon/\n  preamble/\n    PLATFORM_CANON_PREAMBLE.md        # Platform invariants, actor model, API conventions, namespace structure\n  objects/\n    CANON_OBJECT_Catalog_Product.md\n    CANON_OBJECT_Catalog_PriceList.md\n    ...                               # One file per platform object\n  platform/\n    CANON_PLATFORM_MarkdownRenderer.md\n    ...                               # System behaviour not tied to a specific object\n  questions/\n    CANON_OPEN_QUESTIONS.md           # Known unknowns awaiting resolution\n    CANON_RESOLVED_QUESTIONS.md       # Closed questions with confirmed answers\n  templates/\n    CANON_OBJECT_TEMPLATE.md          # Standard template for object canon documents\n    CANON_AUTHORING_SESSION.md        # LLM session prompt for canon authoring\n  scripts/\n    convert_to_docx.py                # Convert canon Markdown files to .docx\n    extract_objects.py                # Extract a namespace/object checklist from the OpenAPI spec\n    extract_canon_schema.py           # Extract paths and schemas for a specific object from the OpenAPI spec\n  .canon/                             # MCP runtime — see .canon/README.md\n```\n\n---\n\n## Working with Canon through Claude\n\nThe `.canon/` directory ships a pair of MCP servers that expose the canon graph to an agent — read-only navigation and patch-based editing. Setup once per clone:\n\n```bash\nnpm install\nnpm run setup\n```\n\n`setup` installs optional ML deps, warms up the local embedding model into `.canon/model-cache/`, builds the runtime bundles into `.canon/dist/`, and emits the user-facing extensions into `dist/` at the repo root with absolute paths baked in for THIS clone.\n\n### Install into Claude Desktop\n\n**Option A — drag-and-drop:**\n```bash\nopen dist/canon-read.mcpb\nopen dist/canon-edit.mcpb\n```\n\n**Option B — paste into `~/Library/Application Support/Claude/claude_desktop_config.json`:**\n```bash\ncat dist/claude_desktop_config.snippet.json\n```\n\nRestart Claude Desktop after installing.\n\n### Patch flow\n\nThe agent never edits source files directly. Edits land under `.patches/\u003cid\u003e/` as whole-file replacements; you commit them deliberately:\n\n```bash\nnpm run apply \u003cpatch-id\u003e            # validate + write into objects/\nnpm run apply \u003cpatch-id\u003e -- --dry-run    # validate + report only\n```\n\n`apply` re-parses + validates from scratch before writing; refuses if anything is unclean. Git flow runs in parallel — branch / commit / push patches and committed canon however your team prefers.\n\n### Verify the install\n\n```bash\nnpm test                            # full unit + integration suite\nnpm run validate                    # parse + validate the live canon\n```\n\n### When to re-run setup\n\n- After cloning fresh\n- After moving / renaming the workdir (the absolute paths in `.mcpb` go stale)\n- After major dist changes (`npm run build` alone updates bundles, but the `.mcpb` manifests are emitted only by `setup`)\n\n---\n\n## Authoring Principles\n\n**If it isn't observed, confirmed, and documented — it isn't canon.**\n\n- **The product manager is the authority, not the LLM.** Challenge, correct, and validate the output at every step. Canon that has not been reviewed by a domain expert is not canon.\n- **Base canon on evidence.** Every rule, behaviour, and attribute must be derived from observed platform behaviour, API responses, or confirmed engineering input. Do not assume or infer.\n- **When in doubt, park it.** Unconfirmed behaviour belongs in the open questions tracker, not in the canon document.\n- **State facts, not opinions.** Canon describes how the platform works, not how it should work.\n- **Be precise with language.** Avoid \"usually\", \"typically\", or \"in most cases\". If a rule has exceptions, document them explicitly.\n- **Respect the invariants.** Platform invariants apply to every object without exception. Do not contradict or restate them per object.\n- **One source of truth.** Reference rules documented elsewhere rather than restating them. Duplication leads to drift.\n- **Version everything.** Every change must be reflected in the document's changelog. Canon is only trustworthy if its history is traceable.\n- **Canon describes the platform, not a vendor's use of it.** Vendor-specific behaviour belongs in vendor canon.\n\n---\n\n## Scripts\n\nThree Python scripts are included in `scripts/` to support canon development workflows.\n\n**Requirements for all scripts:** Python 3. `convert_to_docx.py` additionally requires [pandoc](https://pandoc.org/installing.html). `extract_objects.py` and `extract_canon_schema.py` require a copy of the SoftwareOne Marketplace OpenAPI spec in JSON format — not included in this repo.\n\n---\n\n### `convert_to_docx.py`\n\nConverts all canon Markdown files to `.docx` format using pandoc. Converts every file in `preamble/`, `objects/`, and `platform/` and writes the output to a specified directory.\n\nUsed to produce `.docx` files for upload as Microsoft Copilot Agent knowledge (Copilot Agent Builder requires `.docx` format). Re-run whenever canon files are updated.\n\n```\n# Windows\npython scripts/convert_to_docx.py C:/Users/yourname/Desktop/docx\n\n# macOS / Linux\npython scripts/convert_to_docx.py ~/Desktop/docx\n```\n\n---\n\n### `extract_objects.py`\n\nParses the OpenAPI spec and extracts a structured checklist of all namespaces, objects, child objects, and grandchild objects — formatted as a Markdown backlog ready for use in `CANON_BACKLOG.md`.\n\nUsed to generate or refresh the Full Object Inventory in the backlog when the spec changes.\n\n```\n# Print to stdout\npython scripts/extract_objects.py openapi.json\n\n# Write to a file\npython scripts/extract_objects.py openapi.json canon_checklist.md\n```\n\n---\n\n### `extract_canon_schema.py`\n\nExtracts all API paths and component schemas for a specific platform object from the OpenAPI spec, producing a trimmed JSON file. Follows all `$ref` chains to include every nested schema the object depends on.\n\nUsed to generate a focused, uploadable JSON extract for a canon authoring session — giving the LLM precise schema information for the object being canonised without loading the entire spec.\n\nThe OpenAPI spec can be downloaded from the [SoftwareOne Marketplace developer documentation](https://docs.platform.softwareone.com/developer-resources/rest-api/openapi-specification).\n\n```\n# Top-level object (use --exact to avoid pulling in child object paths)\npython scripts/extract_canon_schema.py openapi.json catalog product --exact\n\n# Child object (no --exact needed — the child path is already specific)\npython scripts/extract_canon_schema.py openapi.json catalog template\n\n# Multi-word object names use hyphens\npython scripts/extract_canon_schema.py openapi.json catalog price-list\n```\n\nThe `--exact` flag restricts matching to paths where the object is the terminal resource segment, excluding paths for child objects (e.g. `catalog/products/{id}/templates` would not be included when extracting `product --exact`). Without `--exact`, all paths containing the namespace and object keyword are matched.\n\nOutput is saved as `openapi_extract_{namespace}_{object}.json` in the same directory as the input spec.\n\n---\n\n## Using this Canon with an LLM\n\nThe structured format of this canon is designed to work well as context for large language models. Loading canon documents as project knowledge in an LLM lets you ask questions about platform behaviour, validate integration assumptions, and accelerate development without digging through documentation manually.\n\n**Recommended approach:**\n- Load `preamble/PLATFORM_CANON_PREAMBLE.md` into your LLM project knowledge first — it establishes the platform invariants and conventions that all object canon builds on.\n- Add the canon documents relevant to your integration (e.g. `objects/CANON_OBJECT_Catalog_PriceList.md`) alongside it. For use with Microsoft Copilot Agent Builder, run `scripts/convert_to_docx.py` first to convert the Markdown files to `.docx` — Copilot Agent Builder requires `.docx` format.\n- You can then ask the LLM to explain behaviours, check assumptions, or walk through lifecycle scenarios for any canonised object.\n\nCanon documents are intentionally precise and unambiguous — which makes them significantly more reliable as LLM context than informal documentation or API reference alone.\n\n### Using Canon as Microsoft Copilot Agent Knowledge\n\nMicrosoft Copilot Agent Builder requires knowledge files in `.docx` format. A conversion script is included in `scripts/` to convert all canon files from Markdown to `.docx` in one step.\n\n**Requirements:** [pandoc](https://pandoc.org/installing.html) and Python 3.\n\n**Usage:**\n```\n# Windows\npython scripts/convert_to_docx.py C:/Users/yourname/Desktop/docx\n\n# macOS\npython scripts/convert_to_docx.py ~/Desktop/docx\n\n# Linux\npython scripts/convert_to_docx.py ~/Documents/docx\n```\n\nThe script converts all files in `preamble/`, `objects/`, and `platform/` and writes `.docx` files to the specified output directory. Re-run it whenever canon files are updated.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftwareone-platform%2Fmpt-marketplace-canon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoftwareone-platform%2Fmpt-marketplace-canon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftwareone-platform%2Fmpt-marketplace-canon/lists"}