Design

Dex Trove — Design

1. Problem

Ananke is the harness layer: registry, resolution, activation, policy and evidence for skills, agents and tools. It has no library of ready-made artifacts to put in that registry. Meanwhile, good artifacts are scattered across community repos (awesome-copilot, anthropics/skills, obra/superpowers, …) and our own work (architecture-as-code, animated SVG diagrams, course and ikigai builders). Each source uses its own layout and licence conventions, and many redistribute material they do not own.

Dex Trove is that library. It:

1. Learns artifacts from mapped upstream repos and from first-party skills.
2. Admits only content whose licence allows redistribution and reuse, item by item, with evidence.
3. Standardises each item into one canonical layout that Ananke can register with no custom code.
4. Ships the result as a Python package (pip install dex-trove, CLI dex).
5. Documents every item on its own page in an Astro site with search, crediting each upstream source.

2. Goals and non-goals

Goals

• G1. One canonical, versioned layout for skill, agent, instruction, prompt, hook, workflow and plugin (bundle) items.
• G2. Per-item licence resolution with an allow-list (MIT, Apache-2.0, BSD, ISC, CC0, …). Unknown means excluded.
• G3. Provenance on every item: source repo, pinned commit, upstream path, upstream URL, licence evidence, content hash.
• G4. Zero-glue Ananke integration: an installed wheel is learnable with ananke registry learn python:dex-trove.
• G5. Installs straight into Claude Code, GitHub Copilot or any directory, for people who don’t use Ananke.
• G6. A static docs site with one page per item, client-side search and a Sources & Inspirations page.
• G7. A repeatable learn → review PR → merge → release to PyPI loop.

Non-goals (v0.x)

• Running or evaluating artifacts. Ananke owns execution, gates and evals.
• Rewriting upstream content. Items are copied byte-for-byte; Dex only adds files next to them.
• A hosted registry server. Ananke’s registry serve and remote federation already do that.
• Canvas extensions and cookbook recipes from awesome-copilot. Those are JS apps, not agent artifacts.

3. Concepts

4. Architecture

flowchart LR
  subgraph Upstream
    A[github/awesome-copilot]
    B[anthropics/skills]
    C[obra/superpowers]
    D[first-party Skills/]
  end
  S[sources.yaml] --> F[fetch<br/>git shallow clone @ pinned commit<br/>or local path]
  A & B & C & D --> F
  F --> AD[adapters<br/>yield raw items]
  AD --> L[licence resolver<br/>item → dir → source → repo]
  L -->|allow| G[guards<br/>size · symlinks · secrets · dupes]
  L -->|deny / unknown| X[trove/EXCLUDED.json]
  G --> N[normaliser<br/>copy bytes + ananke.yaml + dex.json + LICENSE.upstream]
  N --> T[(trove/)]
  T --> CAT[catalog.json · trove.lock.json · THIRD_PARTY_NOTICES.md]
  T --> W[wheel dex-trove<br/>dex_trove/&lt;kind&gt;/&lt;ns.name&gt;/ananke.yaml]
  W --> AN[Ananke<br/>registry learn python:dex-trove]
  W --> CL[dex install → Claude / Copilot / dir]
  CAT --> DOC[Astro site<br/>page per item + search]

4.1 Repository layout

Dex-Trove/
├── sources.yaml              mapped sources (adapter, roots, licence expectations, enabled)
├── trove/                    THE LIBRARY (checked in, reviewed in PRs)
│   ├── skills/<ns>.<name>/   SKILL.md + bundled files (verbatim) + ananke.yaml + dex.json [+ LICENSE.upstream]
│   ├── agents/ instructions/ prompts/ hooks/ workflows/ plugins/
│   ├── catalog.json          index of every item (drives CLI search + docs site)
│   ├── EXCLUDED.json         every rejected item with its reason (licence, secret, size, duplicate)
│   └── trove.lock.json       source → commit learned, timestamp, counts
├── THIRD_PARTY_NOTICES.md    generated attribution (copyright lines + licence per source/item)
├── src/dex_trove/            the `dex` package
├── website/                  Astro docs site (content generated from trove/ at build time)
├── docs/design/              this document + checklist
└── .github/workflows/        ci · docs (Pages) · release (PyPI) · learn (scheduled PR)

4.2 Canonical item layout

trove/skills/awesome-copilot.git-commit/
├── SKILL.md              ← upstream, unmodified
├── scripts/…             ← upstream, unmodified
├── LICENSE.upstream      ← governing licence text, only when the item didn't ship one
├── ananke.yaml           ← generated Ananke manifest (strict schema)
└── dex.json              ← generated provenance + catalog record

Upstream bytes are never modified. That keeps copyright notices intact, makes re-learn diffs honest and lets dex.json.files hashes prove nothing drifted.

Why <namespace>.<name> flat directories: Ananke’s Python importer only looks for manifests at most four path parts deep inside a wheel (dex_trove/skills/<ns.name>/ananke.yaml). A nested <ns>/<name> would be invisible to it. The flat form also mirrors Ananke’s own installed layout (<namespace>.<name>@<version>).

4.3 Kind mapping

5. Licence policy

Redistribution through PyPI is distribution, so only content we may copy and share goes in.

Resolution order (most specific wins):

1. Item frontmatter license: when it is a valid SPDX expression. If it points at a file (“Complete terms in LICENSE.txt”), go to step 2.
2. A licence file in the item directory (LICENSE*, COPYING*), classified by text, not filename.
3. A licence file in an ancestor directory inside the source (e.g. src/fetch/LICENSE).
4. The source’s repo-root licence, classified by text.
5. sources.yaml license.default, allowed only for first_party: true sources we own.

Text classification uses normalised-text fingerprints for the common licences, plus explicit deny markers such as “All rights reserved” without a grant, “governed by your agreement with”, or “may not … redistribute”. A deny marker beats an allow fingerprint.

Why per-item and by text: this is not hypothetical. On 2026-10-19:

• anthropics/skills has no repo licence; its example skills ship Apache-2.0 LICENSE.txt files, while docx, pdf, pptx and xlsx ship proprietary, source-available terms.
• ComposioHQ/awesome-claude-skills redistributes those same proprietary document skills.
• Three awesome-copilot skills say license: Complete terms in LICENSE.txt.

SPDX expressions with OR pass if any branch is allowed. With AND, every branch must be allowed.

Nested licences. Licence files inside an item, such as bundled fonts or vendored code, are classified too. Any denied one excludes the whole item. Allowed ones are recorded as license.components; for example, the OFL-1.1 fonts in anthropic/canvas-design. Only strict licence filenames count (LICENSE*, COPYING*, *-OFL.txt). A reference doc that merely describes a licence, such as pdftk-server/references/pdftk-server-license.md, is content, not terms.

Declared but not shipped. When an item declares Apache-2.0 in frontmatter but no Apache text exists upstream (7 awesome-copilot items), Dex writes the canonical text from dex_trove/license_texts/ as LICENSE.upstream, because Apache §4(a) requires recipients to receive a copy.

Attribution: MIT, BSD and Apache require the copyright and licence notice to travel with the copy. Each item keeps its own licence file, or gets LICENSE.upstream. Apache NOTICE files are copied too. THIRD_PARTY_NOTICES.md aggregates everything and ships in the sdist and wheel.

Third-party assets inside first-party skills: marvellous-aws-architecture-docs/assets/icons/* are AWS Architecture Icons. AWS grants use in diagrams, not redistribution as an icon set. Dex excludes that folder via sources.yaml exclude: globs. The skill’s own scripts/fetch_icons.py pulls them on demand from the MIT-licensed diagrams wheel, and archlib falls back to text boxes until then.

6. Guards (beyond licence)

| Ananke secret rules | Dex mirrors Ananke’s registration-time scanner (broader than Dex’s own) | keep, but record secret_flags and tag ananke-secret-flag; dex ananke sync skips unless --include-flagged |

The two secret scanners have different jobs. Dex’s own patterns target real key formats and exclude on a hit. Ananke’s are broader (e.g. api_key = "<16+ chars>") and, on the first full run, refused 9 security-teaching items for placeholders like "PINECONE_API_KEY" and sk_live_…. Dropping those items from the library would lose good content. Shipping them silently would make ananke registry learn python:dex-trove exit non-zero. Flagging them keeps both behaviours honest.

Upstream content stays untrusted. Dex never executes it, and the docs site renders it through rehype-sanitize.

7. Versioning

• Package: SemVer, 0.x while the format settles. Every release bumps the version, even when only content changed.
• Items: each item carries its own SemVer in ananke.yaml. First learn gives 1.0.0; if a re-learn changes the content hash, the patch is bumped; an upstream-declared version (e.g. plugin.json.version) wins when present. So ananke registry learn registers a new immutable version only when content actually changed.
• Sources: trove.lock.json pins the commit each source was learned at. A release is fully reproducible.

8. CLI (dex)

REF is namespace/name, kind:namespace/name or a unique bare name.

9. Ananke integration

Works today, with no Ananke change:

pip install ananke-plexus dex-trove
ananke registry init
ananke registry learn python:dex-trove     # every item's ananke.yaml is discovered inside the wheel
# or selectively, through Dex:
dex ananke sync --kind skill --source neo-pragnya

Each manifest sets license, metadata.repository, tags and ananke_id: urn:dex-trove:<kind>:<ns>:<name>, so Ananke’s registry keeps identity stable across versions. Ananke’s own licence policy ([licenses] allow) applies on top of Dex’s. That’s defence in depth.

Proposed Ananke change (the “special setting”), tracked separately:

1. pip install "ananke-plexus[dex]" extra, which pulls dex-trove.

2. Policy setting:

   # .ananke/registry/policy.toml
   [troves]
   dex-trove = { enabled = true, kinds = ["skill", "agent"], sources = ["*"], channel = "candidate" }

   ananke registry init and ananke sync then auto-learn python:dex-trove when it is installed and enabled, and re-learn when the installed dex-trove version changes.

3. Dex exposes an entry point ananke.troves: dex-trove = dex_trove.ananke_bridge:trove_root so Ananke can find any trove package generically, not just Dex.

10. Docs site

Astro (same stack as VICHARA), static, deployed to GitHub Pages.

Content is generated at build time by dex docs export, so the site can’t drift from the trove. The export rewrites relative image and link targets in upstream Markdown to the upstream repo, pinned to the learned commit: raw.githubusercontent.com for images and github.com/…/blob/<commit>/ for links. Otherwise they would 404 on the site, and Astro would try to bundle them as local assets and fail the build.

11. Delivery loop

flowchart LR
  cron[weekly learn workflow] --> learn[dex learn] --> pr[PR: trove diff + EXCLUDED diff]
  pr --> review[human review: new items, licence changes, exclusions]
  review --> merge[merge to main] --> ci[ci: dex validate · pytest · astro build]
  ci --> tag[tag vX.Y.Z] --> pypi[release workflow: uv build → PyPI trusted publishing]
  merge --> pages[docs workflow → GitHub Pages]

A licence that changes upstream (e.g. MIT → proprietary) makes the item disappear from the next learn and show up in EXCLUDED.json. The PR diff makes that visible to a reviewer.

12. Source map

Licences were verified through the GitHub API on 2026-10-19. “Repo” is the repo-level licence; items are still resolved one by one.

13. Risks and open questions

Edit this page on GitHub ↗