SoulMap AI

SoulMap AI is a personal AI brand built as a reflective companion.

Its purpose is simple: help people hear themselves more clearly without handing their authority away.

This is not an AI built to sound all-knowing, emotionally sticky, or spiritually inflated. It is built as a mirror, not a guru. Its value comes from careful language, clear boundaries, and a refusal to turn certainty into a product.

What SoulMap is

• a reflective companion
• a high-trust mirror for patterns, emotions, and inner conflict
• a bounded AI system designed to strengthen self-trust
• a content-first knowledge base with a small Python enforcement and tooling layer

What SoulMap is not

• not a therapist
• not a guru
• not a diagnosis tool
• not a predictor of fate, destiny, or future outcomes
• not a replacement for real-world support

Why this repo exists

This repository is the working source for the SoulMap AI system.

It contains:

• the baseline doctrine and package contract in SOULMAP.md
• the shipped knowledge base in skills/
• the canonical Python runtime and safety logic in src/soulmap/runtime/
• the canonical local tooling in src/soulmap/devtools/ and small setup/CI helpers in scripts/
• the operational and maintainer docs in docs/

The repo is designed to keep brand, safety, packaging, and implementation aligned.

Core stance

• mirror-first, not advice-first
• anti-dependency by design
• clarity over spectacle
• honest AI identity
• one active framework at a time
• user independence as the success condition

Founder point of view

SoulMap AI is being built around a clear belief: vulnerable people should not have to trade self-trust for reflection.

Too many AI and self-help systems answer uncertainty with authority. SoulMap is built to do the opposite. It reflects what is already alive in the user without pretending to know better than they do.

Repository shape

The most important surfaces are:

• SOULMAP.md, baseline doctrine, safety law, response behavior, and shipped package guide
• SKILL.md, top-level package entry point
• skills/, frameworks, brand doctrine, safety guidance, voice, and meta layers (including the shipped response and redirect templates in skills/meta/)
• src/soulmap/runtime/, selectors, detectors, guards, and runtime support
• src/soulmap/devtools/, canonical format, lint, eval, and packaging entry points
• docs/, developer, tester, privacy, operations, and upload guidance

Quick start

uv python install 3.11
bash scripts/bootstrap_venv.sh
uv run soulmap format
uv run soulmap lint
uv run soulmap test -n auto -q

bash scripts/bootstrap_venv.sh now syncs the local environment from uv.lock and targets Python 3.11 explicitly.

Build artifacts

uv run soulmap build
uv run soulmap dev

Outputs:

• dist/soulmap-ai.zip, standard knowledge archive without .claude-plugin/
• dist/soulmap-ai.skill, skill package with .claude-plugin/ preserved
• .soulmap/zip/ and .soulmap/skill/, verified extracted trees generated by uv run soulmap dev

For packaging and upload details, see docs/operations/UPLOAD.md.

Distribution boundary

The Python wheel and source distribution are local developer/test tooling surfaces. They provide the soulmap CLI and repository validation code, but they are not standalone knowledge-base runtimes and do not replace the repository's skills/ source tree.

For use in AI tools, import the generated dist/soulmap-ai.skill or dist/soulmap-ai.zip artifact. Those artifacts are the supported distribution surface for SoulMap doctrine and package knowledge; the Python distribution is not an AI Skill installer.

Where to start

• doctrine and package truth: SOULMAP.md
• structural source of truth: docs/engineering/repo-contract.md
• safety architecture, end to end: docs/engineering/safety-architecture.md
• intentional architecture limitations: docs/engineering/known-limitations.md
• Library vs Framework boundary: docs/engineering/library-vs-framework.md
• project roadmap: docs/ROADMAP.md
• developer workflow: docs/engineering/DEV.md
• testing and eval workflow: docs/engineering/TESTER.md
• privacy and operations: docs/operations/PRIVACY.md, docs/operations/OPERATIONS.md

For AI tools and local maintainer layers

Use AGENTS.md first. It is the baseline contract for AI coding agents working in this repository, covering project shape, build and test commands, and workflow rules, and it points to SOULMAP.md for SoulMap's own doctrine. CLAUDE.md is a symlink to AGENTS.md, so Claude Code reads the same file as any other coding agent.

If this checkout also contains local workflow layers, treat them as supplemental only:

• .claude/ for the local Claude workflow layer, see .claude/README.md

This layer does not replace AGENTS.md.

For skill-package metadata preserved only in .skill artifacts, see .claude-plugin/README.md.

Release posture

SoulMap should be shipped only when the repo still tells one consistent story across:

• doctrine
• safety
• packaging
• tests and evals
• public-facing claims

That discipline matters as much as any single framework or feature.