embeddings-lens

Explore the emotions, ideas, and connotations of text through an embedding model's lens: an agent-first CLI that reads a given text back through the geometry of an embedding space and reports what the model associates with it, with provenance.

What you get

• An agent-first CLI cited from teken (afi-cli) — the runtime package has no third-party dependencies.
• A mesh identity — culture.yaml (suffix + backend) and the matching resident prompt file (CLAUDE.md, since this template runs backend: claude). The mesh resident is one of two separate selections over this clone — see Two selections, not one below.
• Four harness prompt files, one per agent harness, each read by exactly one of them (see Prompt files by harness below). All four harnesses are usable interactively regardless of which one culture.yaml names as the mesh resident.
• The canonical guildmaster skill kit (11 skills) under .claude/skills/, vendored cite-don't-import. See docs/skill-sources.md.
• A build + deploy baseline — pytest, lint, the agent-first rubric gate, and PyPI Trusted Publishing wired into GitHub Actions.

Prompt files by harness

Four harnesses, four root files, no shared base — each file is read by exactly one harness:

Claude Code — CLAUDE.md is the fullest write-up of the repo's conventions; read it first.

Pi / associate — AGENTS.override.md replaces this directory's AGENTS.md/CLAUDE.md in Pi's context layer, so Pi does not inherit CLAUDE.md. .pi/SYSTEM.md replaces Pi's default system prompt with the non-coding associate identity (read/find/summarize only).

colleague — colleague's prompt cascade is AGENTS.md → AGENTS.colleague.md → AGENTS.colleague.<model>.md. This repo ships only the middle layer: there is no AGENTS.md (a shared base across harnesses was considered and rejected) and no per-model override file.

Qwen Code — Qwen Code reads QWEN.md and AGENTS.md; since there is no AGENTS.md, QWEN.md is its sole source of guidance.

There is intentionally no AGENTS.md at the root — each harness gets an unrelated file rather than cascading from a shared base.

Two selections, not one

It is tempting to read "switch harness" as one decision. It is actually two, and this template exists partly to keep them separate:

1. The interactive harness — which binary you run (claude, pi, colleague, qwen). cd into the clone and run any of them; all four are live simultaneously, and none of them requires editing a file or flipping a switch. A harness can be force-selected for one invocation (e.g. a CI smoke check) without ever touching culture.yaml — see docs/automation-contract.md.
2. The mesh resident — the single backend culture.yaml declares, which is what the Culture daemon starts and what steward doctor checks. guild harness use <name> changes only this.

culture.yaml's backend affects (2) only. It never affects which harness you can invoke interactively in (1). See docs/harness-selection.md for the full writeup, including who reads this config and why existing siblings are not retrofitted by this arc.

Quickstart

uv sync
uv run pytest -n auto                 # run the test suite
uv run embeddings-lens whoami  # identity from culture.yaml
uv run embeddings-lens learn   # self-teaching prompt (add --json)
uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs

CLI

Every command supports --json. Results go to stdout, errors/diagnostics to stderr (never mixed). Exit codes: 0 success, 1 user error, 2 environment error, 3+ reserved.

Make it your own

1. Rename the package embeddings_lens/ and the embeddings-lens CLI/dist name throughout pyproject.toml, the package, tests/, sonar-project.properties, and this README.md. The name is hard-coded in ~100 places, so list every occurrence first — see the git grep discovery command in CLAUDE.md, the authoritative rename procedure.
2. Edit culture.yaml with your suffix and backend.
3. Rewrite CLAUDE.md for your agent and run /init. Rewrite the other three harness files (AGENTS.override.md + .pi/SYSTEM.md, AGENTS.colleague.md, QWEN.md) too if your agent uses those harnesses — don't let them drift out of sync with CLAUDE.md.
4. Re-vendor only the skills you need from guildmaster (see docs/skill-sources.md).

See CLAUDE.md for the full conventions (version-bump-every-PR, the cicd PR lane, deploy setup).

License

Apache 2.0 — see LICENSE.