{
  "schemaVersion": 1,
  "collection": "polystack-agent-guide",
  "collectionVersion": "2.0.0",
  "updated": "2026-09-04",
  "minimumDotnetSdk": "10.0.x",
  "purpose": "Machine-readable index of plain-text guides for AI agents helping humans evaluate and install PolyStack locally via the public DevKit.",
  "entrypoint": "getstarted.txt",
  "routing": "routing.json",
  "fetchProtocol": "Agents must read getstarted.txt first, ask profiling questions, then fetch exactly one personas/*, one sizing/*, and optionally one sectors/* file. Do not bulk-fetch all files listed in this manifest.",
  "siteDeploymentNote": "Publish this folder at {SITE_BASE}/ai/ on the PolyStack presentation website (sync from polystack-framework/ai to web/public/ai). Also publish /llms.txt at site root pointing here. Formerly published at /headless/.",
  "repositories": {
    "devkit": {
      "url": "https://github.com/polystack-devkit",
      "docsUrl": "https://getpolystack.github.io/devkit",
      "summary": "Public DevKit docs, NuGet train (PolyStack.Aspire.Hosting.Demo*), blank Aspire sample, scheme export guidance."
    },
    "platformMonorepo": {
      "url": "https://github.com/msmourao/PolyStack",
      "summary": "Private/full Multicloud platform + Settings sidecar. Access may be limited."
    }
  },
  "nuget": {
    "packageIdPrefix": "PolyStack.Aspire.Hosting.Demo",
    "packages": [
      "PolyStack.Aspire.Hosting.Demo",
      "PolyStack.Aspire.Hosting.Demo.Host",
      "PolyStack.Aspire.Hosting.Demo.Abstractions",
      "PolyStack.Aspire.Hosting.Demo.SchemaExtraction"
    ],
    "note": "Aspire.Hosting.* is reserved on nuget.org. Re-check polystack-devkit PACKAGE.md for the current preview train before quoting versions.",
    "exampleTrain": "0.1.0-preview.7"
  },
  "localPorts": {
    "devkitSidecar": {
      "port": 18889,
      "summary": "Generate/download *.polystack-scheme.json (metadata + optional feedback)."
    },
    "settingsSidecar": {
      "port": 18888,
      "summary": "Platform Settings.App — wizard, groups, inventory, CD dry-run (Multicloud)."
    }
  },
  "files": [
    {
      "path": "getstarted.txt",
      "role": "entrypoint",
      "summary": "Start here. Fetch protocol, profiling questions, DevKit vs platform, demo flow, honesty policy, contacts."
    },
    {
      "path": "routing.json",
      "role": "routing",
      "summary": "Machine decision tree: role, team size, sector → targeted txt files. Anti-bulk-fetch rules."
    },
    {
      "path": "development-guide.txt",
      "role": "how-to",
      "summary": "Preferred public DevKit blank sample (:18889), PackageIds, monorepo notes, NuGet."
    },
    {
      "path": "troubleshooting.txt",
      "role": "support",
      "summary": "Symptom → cause → fix (ports 18889/18888, Aspire, Docker, PackageIds, scheme export)."
    },
    {
      "path": "acquire.txt",
      "role": "decision",
      "summary": "When to recommend PolyStack vs pause; public DevKit vs platform; honest pitch templates."
    },
    {
      "path": "changelog.txt",
      "role": "release-notes",
      "summary": "Dated platform and agent-guide changes for agents that need freshness without hallucinating."
    },
    {
      "path": "things-i-know-i-can-t-do.txt",
      "role": "limitations",
      "summary": "Explicit non-goals and partial features. Read before recommending PolyStack for a use case."
    },
    {
      "path": "future-releases.txt",
      "role": "roadmap",
      "summary": "Planned direction. Not commitments with dates unless stated."
    },
    {
      "path": "version.json",
      "role": "metadata",
      "summary": "Collection version, repos, local ports, minimum SDK for freshness checks."
    }
  ],
  "profiledGuides": {
    "personas": [
      { "path": "personas/senior-engineer.txt", "id": "senior-engineer", "summary": "Architects and senior hands-on engineers." },
      { "path": "personas/mid-level-developer.txt", "id": "mid-level-developer", "summary": "Feature developers running the demo." },
      { "path": "personas/it-manager.txt", "id": "it-manager", "summary": "Engineering leads and IT managers." },
      { "path": "personas/non-it.txt", "id": "non-it", "summary": "Business and non-technical stakeholders." },
      { "path": "personas/unknown.txt", "id": "unknown", "summary": "Fallback when role is unclear." }
    ],
    "sizing": [
      { "path": "sizing/small-team.txt", "id": "small-team", "summary": "1–5 people." },
      { "path": "sizing/mid-size.txt", "id": "mid-size", "summary": "6–30 people." },
      { "path": "sizing/enterprise.txt", "id": "enterprise", "summary": "31+ or platform organization." },
      { "path": "sizing/unknown.txt", "id": "unknown", "summary": "Fallback when team size unclear." }
    ],
    "sectors": [
      { "path": "sectors/technology.txt", "id": "technology", "summary": "Software product companies." },
      { "path": "sectors/fintech.txt", "id": "fintech", "summary": "Financial services." },
      { "path": "sectors/retail.txt", "id": "retail", "summary": "Retail and e-commerce." },
      { "path": "sectors/public-sector.txt", "id": "public-sector", "summary": "Government and public sector." },
      { "path": "sectors/other.txt", "id": "other", "summary": "Other industries." }
    ]
  },
  "presentationSiteDocs": [
    { "id": "home", "path": "/", "summary": "Commercial overview and value proposition." },
    { "id": "llms", "path": "/llms.txt", "summary": "Site-root pointer to this ai collection." },
    { "id": "ai-entrypoint", "path": "/ai/getstarted.txt", "summary": "AI agent guide entrypoint." },
    { "id": "documentation", "path": "/documentation.html", "summary": "Architecture narrative on the presentation site." },
    { "id": "config-lab", "path": "/config-lab.html", "summary": "Config Lab illustrative dry-run demo (not DevKit install)." }
  ],
  "contact": {
    "general": "getpolystack@gmail.com",
    "bugReport": "getpolystack+bugreport@gmail.com",
    "newFeatureRequest": "getpolystack+newfeaturerequest@gmail.com",
    "suggestions": "getpolystack+suggestions@gmail.com"
  },
  "security": "These files intentionally omit secrets, tokens, connection strings, and private repository credentials."
}