simplicio-mapper 0.7.1__tar.gz → 0.7.3__tar.gz

{simplicio_mapper-0.7.1 → simplicio_mapper-0.7.3}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.7.3] - 2026-06-01
+
+### Changed
+- Restored the original operational README guide under the new growth-oriented landing page, preserving setup, architecture, video, mapper flags, and endpoint inventory details.
+- Added Project DNA notes across localized READMEs and updated the globalization standard to require additive README refreshes rather than replacing repo-specific substance.
+- Included the richer README in the Python and npm package metadata for the refreshed documentation release.
+
+## [0.7.2] - 2026-06-01
+
+### Changed
+- Rebuilt the README as a multilingual growth page inspired by Understand Anything and 50k+ star repository patterns.
+- Added canonical translations under `READMEs/` for the full Simplicio language set and documented the new README globalization standard.
+- Included the translations and globalization standard in package source metadata.
+
 All notable changes to **LLM Project Mapper** are documented in this file.
 
 Format follows [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

{simplicio_mapper-0.7.1 → simplicio_mapper-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simplicio-mapper
-Version: 0.7.1
+Version: 0.7.3
 Summary: Python-first project mapper that emits .simplicio/project-map.json and precedent-index.json for the Simplicio ecosystem.
 Project-URL: Homepage, https://github.com/wesleysimplicio/simplicio-mapper
 Project-URL: Repository, https://github.com/wesleysimplicio/simplicio-mapper
@@ -47,6 +47,9 @@ Description-Content-Type: text/markdown
 
 # simplicio-mapper
 
+> README globalization release: the GitHub README now ships with 15 language entry points, Star History, ecosystem graph, and a proof-first structure. The package contract below remains the canonical PyPI technical reference.
+
+
 Python-first project mapper for the Simplicio ecosystem. It scans a repository
 and emits machine-readable artifacts that agents and tooling can consume
 without parsing the human-readable markdown docs:

{simplicio_mapper-0.7.1 → simplicio_mapper-0.7.3}/PYPI.md

@@ -1,5 +1,8 @@
 # simplicio-mapper
 
+> README globalization release: the GitHub README now ships with 15 language entry points, Star History, ecosystem graph, and a proof-first structure. The package contract below remains the canonical PyPI technical reference.
+
+
 Python-first project mapper for the Simplicio ecosystem. It scans a repository
 and emits machine-readable artifacts that agents and tooling can consume
 without parsing the human-readable markdown docs:

{simplicio_mapper-0.7.1 → simplicio_mapper-0.7.3}/README.md

@@ -1,4 +1,103 @@
-# LLM Project Mapper
+<h1 align="center">simplicio-mapper</h1>
+
+<p align="center">
+  <strong>Map any repository into AI-readable context: project map, precedent index, architecture inventory, symbol index, call graph, and docs.</strong><br />
+  <em>Commands stay in English so they can be copied exactly.</em><br />
+  <a href="https://wesleysimplicio.github.io/llm-project-mapper/">Live docs: wesleysimplicio.github.io/llm-project-mapper</a>
+</p>
+
+<p align="center">
+<a href="https://github.com/wesleysimplicio/simplicio-mapper/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/wesleysimplicio/simplicio-mapper?style=flat-square" /></a>
+<a href="https://pypi.org/project/simplicio-mapper/"><img alt="PyPI" src="https://img.shields.io/pypi/v/simplicio-mapper.svg?style=flat-square" /></a>
+<a href="https://www.npmjs.com/package/@wesleysimplicio/llm-project-mapper"><img alt="npm" src="https://img.shields.io/npm/v/%40wesleysimplicio%2Fllm-project-mapper.svg?style=flat-square" /></a>
+<a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-yellow?style=flat-square" /></a>
+</p>
+
+<p align="center">
+<a href="README.md">English</a> | <a href="READMEs/README.pt-BR.md">Português</a> | <a href="READMEs/README.es-ES.md">Español</a> | <a href="READMEs/README.ja-JP.md">日本語</a> | <a href="READMEs/README.ko-KR.md">한국어</a> | <a href="READMEs/README.zh-CN.md">简体中文</a> | <a href="READMEs/README.it-IT.md">Italiano</a> | <a href="READMEs/README.fr-FR.md">Français</a> | <a href="READMEs/README.ru-RU.md">Русский</a> | <a href="READMEs/README.pl-PL.md">Polski</a> | <a href="READMEs/README.hi-IN.md">हिन्दी</a> | <a href="READMEs/README.ar-SA.md">العربية</a> | <a href="READMEs/README.he-IL.md">עברית</a> | <a href="READMEs/README.ms-MY.md">Bahasa Melayu</a> | <a href="READMEs/README.id-ID.md">Bahasa Indonesia</a>
+</p>
+
+<p align="center">
+  <img src="assets/llm-project-mapper-hero.png" alt="simplicio-mapper preview" width="860" />
+</p>
+
+<p align="center">
+  <img src="assets/overlay-install.svg" alt="Overlay install flow" width="860" />
+</p>
+
+---
+
+## The short version
+
+Map any repository into AI-readable context: project map, precedent index, architecture inventory, symbol index, call graph, and docs.
+
+## Project DNA
+
+simplicio-mapper is the map before the plan. Its value is not only the artifact names; it is the habit it teaches agents: read the repository, preserve shared context, expose architecture, and make future work cheaper. The original guide explained that operational philosophy in detail, so this refresh restores it under the sharper global landing page.
+
+The new first screen is the doorway; the restored guide below is the workshop. This README should help a stranger understand the promise quickly and still give an operator enough depth to run, validate, and extend the project.
+
+## Quick Start
+
+```bash
+pip install -U simplicio-mapper
+simplicio-mapper index . --json
+simplicio-mapper docs . --json
+simplicio-mapper endpoints ./web --against ./api --json
+```
+
+## What it does
+
+- Generates versioned .simplicio artifacts agents can read before planning.
+- Works as both Python CLI and npm starter package.
+- Builds architecture, symbol and call graph artifacts without forcing a framework.
+- Exports markdown docs for wiki/review workflows while keeping remote publishing opt-in.
+
+## Why this README is built to earn attention
+
+- clear first-screen promise
+- language links before installation
+- badges and a visual hero for fast trust
+- copy-ready quick start
+- proof before long reference material
+- star history for social proof
+
+## How it works
+
+```mermaid
+flowchart LR
+  mapper["simplicio-mapper
+repo context"] --> current["simplicio-mapper
+this project"]
+  prompt["simplicio-prompt
+reasoning runtime"] --> current
+  current --> evidence["validated evidence
+tests, docs, screenshots"]
+  current --> sprint["simplicio-sprint
+delivery loop"]
+```
+
+## Proof and validation
+
+- Current local mapper version is 0.7.x with background indexing and docs-only modes.
+- This repo is the canonical standard for visible, versioned .simplicio artifacts.
+- It now carries the README globalization standard used across this workspace.
+
+## Simplicio ecosystem
+
+- [simplicio-mapper](https://github.com/wesleysimplicio/simplicio-mapper) supplies repo context before interpretation.
+- [simplicio-cli](https://github.com/wesleysimplicio/simplicio-dev-cli) executes focused code tasks with verification.
+- [simplicio-prompt](https://github.com/wesleysimplicio/simplicio-prompt) provides fan-out and consensus runtime patterns.
+- [simplicio-sprint](https://github.com/wesleysimplicio/simplicio-sprint) turns cards into draft PR delivery loops.
+
+## Documentation standard
+
+- [SIMPLICIO_INTEGRATION.md](SIMPLICIO_INTEGRATION.md)
+- [docs/readme-globalization-standard.md](docs/readme-globalization-standard.md)
+
+## Original Field Guide
+
+The section below restores the project-specific README material that existed before the globalization pass. Keep this substance when refreshing the top-level narrative: add polish, do not erase operational memory.
 
 > 🇺🇸 English. Leia em português: [README.pt-BR.md](README.pt-BR.md).
 > Live docs site: [wesleysimplicio.github.io/llm-project-mapper](https://wesleysimplicio.github.io/llm-project-mapper/)
@@ -11,7 +110,7 @@ AI-friendly, stack-neutral repository scaffold. Drop it into **any** project —
 
 > Visual summary: drop the starter into a messy software project and it turns scattered context into structure, reusable skills, tests, docs, and guardrails for AI coding agents.
 
-### Watch: why llm-project-mapper? (53s)
+#### Watch: why llm-project-mapper? (53s)
 
 [![Watch the video](video/assets/why-cover.png)](https://github.com/wesleysimplicio/llm-project-mapper/raw/main/video/assets/why-llm-project-mapper.mp4)
 
@@ -19,7 +118,7 @@ AI-friendly, stack-neutral repository scaffold. Drop it into **any** project —
 
 ---
 
-## Operational Docs For Agents
+### Operational Docs For Agents
 
 This starter now includes generic, fill-in templates that make any project easier for agents to operate:
 
@@ -34,7 +133,7 @@ This starter now includes generic, fill-in templates that make any project easie
 
 Fill these files after installing the starter in a real project. The goal is to reduce discovery time for humans and agents without forcing a framework.
 
-## Machine-Readable Mapper Outputs
+### Machine-Readable Mapper Outputs
 
 The bootstrap also writes `.simplicio/project-map.json` and
 `.simplicio/precedent-index.json` for tools such as `simplicio-dev-cli` and
@@ -48,7 +147,7 @@ npx @wesleysimplicio/llm-project-mapper map --incremental
 npx @wesleysimplicio/llm-project-mapper update
 ```
 
-### New: standalone Python CLI
+#### New: standalone Python CLI
 
 The mapper now ships as a Python package with lightweight performance
 dependencies (`orjson` for JSON serialization and `diskcache` for a persistent
@@ -105,7 +204,7 @@ building client demand.
 
 ---
 
-## Patterns
+### Patterns
 
 - Canonical spec: [YOOL_TUPLE_HAMT.md](YOOL_TUPLE_HAMT.md)
 - Receipts schema and storage conventions: [Receipt schema](YOOL_TUPLE_HAMT.md#184-receipt-schema-reference)
@@ -114,7 +213,7 @@ The yool / tuple / HAMT pattern is the capability-addressing model this scaffold
 
 ---
 
-## TL;DR — get going in 60 seconds
+### TL;DR — get going in 60 seconds
 
 Pick **one** of the install paths below and run it inside your project folder. The bootstrap now starts an automatic local mapping pass immediately; `INIT.md` becomes an optional refinement step for a stronger agent.
 
@@ -129,23 +228,23 @@ Same command everywhere. No bash dependency, no clone, no global install.
 
 ---
 
-## What LLM Project Mapper Changes
+### What LLM Project Mapper Changes
 
 The point of the starter is not “more files”. It is faster agent execution with less ambiguity, less tribal knowledge, and safer delivery loops.
 
-#### 01 · From project chaos to operational structure
+##### 01 · From project chaos to operational structure
 
 ![Project transformation](assets/llm-project-mapper-transformation.png)
 
 > Drop the starter into an existing codebase and it converts scattered context into repeatable docs, validation, agent instructions, and delivery guardrails.
 
-#### 02 · Shared context for parallel agents
+##### 02 · Shared context for parallel agents
 
 ![Multi-agent collaboration](assets/llm-project-mapper-multi-agent.png)
 
 > Agents stop working as isolated chat sessions and start collaborating around the same project map: architecture, tasks, checks, and output expectations.
 
-#### 03 · A stable foundation for safe speed
+##### 03 · A stable foundation for safe speed
 
 ![Operational foundation](assets/llm-project-mapper-foundation.png)
 
@@ -153,7 +252,7 @@ The point of the starter is not “more files”. It is faster agent execution w
 
 ---
 
-## Prerequisites
+### Prerequisites
 
 | Requirement | macOS | Linux | Windows |
 |---|---|---|---|
@@ -166,7 +265,7 @@ Pick **one** runtime: `npx` works everywhere; `bootstrap.sh` for Unix shells; `b
 
 ---
 
-## What it ships
+### What it ships
 
 ```
 your-project/
@@ -195,9 +294,9 @@ Stack-neutral: the bootstrap now fills the first pass automatically from the rea
 
 ---
 
-## Install paths
+### Install paths
 
-### A. `npx` — recommended, cross-platform, zero clone
+#### A. `npx` — recommended, cross-platform, zero clone
 
 ```bash
 # inside your project folder (works on macOS, Linux, Windows)
@@ -211,13 +310,13 @@ Runs interactively. Asks **only**:
 
 Everything else — `PRODUCT_NAME`, stack, dependencies — auto-detected from `package.json` / `pyproject.toml` / `go.mod` / `*.csproj` / `Cargo.toml` / `pubspec.yaml` / `composer.json` / `Gemfile` / `mix.exs` / `pom.xml` / `build.gradle*`.
 
-#### Non-interactive (CI / scripts)
+##### Non-interactive (CI / scripts)
 
 ```bash
 npx @wesleysimplicio/llm-project-mapper --yes --cli skip --append-gitignore no
 ```
 
-#### Update an existing starter overlay
+##### Update an existing starter overlay
 
 ```bash
 npx @wesleysimplicio/llm-project-mapper@latest --update
@@ -225,13 +324,13 @@ npx @wesleysimplicio/llm-project-mapper@latest --update
 
 This is equivalent to `--yes --force --append-gitignore no --cli skip`: it refreshes starter-managed files, leaves `.gitignore` untouched unless explicitly requested, preserves existing instruction files, and does not launch an agent.
 
-#### Preview without writing
+##### Preview without writing
 
 ```bash
 npx @wesleysimplicio/llm-project-mapper --dry-run --yes
 ```
 
-#### Full flag list
+##### Full flag list
 
 | Flag | Purpose |
 |---|---|
@@ -246,7 +345,7 @@ npx @wesleysimplicio/llm-project-mapper --dry-run --yes
 | `-v, --version` | Print version |
 | `-h, --help` | Show help |
 
-#### Python mapper flags
+##### Python mapper flags
 
 | Flag | Purpose |
 |---|---|
@@ -264,7 +363,7 @@ npx @wesleysimplicio/llm-project-mapper --dry-run --yes
 | `--verbose` | Show index refresh progress |
 | `--out <dir>` | Artifact directory, defaulting to `.simplicio` |
 
-### B. `bootstrap.sh` — Unix shells (macOS / Linux / Git Bash / WSL)
+#### B. `bootstrap.sh` — Unix shells (macOS / Linux / Git Bash / WSL)
 
 Clone the starter and run the script:
 
@@ -275,7 +374,7 @@ chmod +x ./bootstrap.sh   # only the first time
 ./bootstrap.sh
 ```
 
-### C. `bootstrap.ps1` — native Windows (PowerShell)
+#### C. `bootstrap.ps1` — native Windows (PowerShell)
 
 ```powershell
 git clone --depth=1 https://github.com/wesleysimplicio/llm-project-mapper.git tmp-starter
@@ -291,7 +390,7 @@ powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1
 
 All three paths produce the same result and ask the same two questions.
 
-### D. Overlay onto an existing project (private, gitignored)
+#### D. Overlay onto an existing project (private, gitignored)
 
 Want to drop the starter into a project that already has its own git, **without polluting the host repo**? Each dev installs locally, files stay gitignored. Full step-by-step in [INSTALL.md](INSTALL.md). Short version:
 
@@ -310,7 +409,7 @@ rm -rf /tmp/llm-project-mapper-src
 
 ---
 
-## CLI handoff — supported agents
+### CLI handoff — supported agents
 
 After scaffolding and auto-mapping, the bootstrap can optionally launch a CLI/LLM with `INIT.md` for a second-pass refinement. Detected installs get a `[installed]` mark in the menu.
 
@@ -334,7 +433,7 @@ For Copilot CLI (no native agent loop), the bootstrap copies the prompt to your
 
 ---
 
-## What `INIT.md` does — the safety contract
+### What `INIT.md` does — the safety contract
 
 When the chosen CLI runs `INIT.md`, it reads `.starter-meta.json` and follows three hard rules:
 
@@ -361,9 +460,9 @@ Anything outside this whitelist **and** not from the starter template = untouche
 
 ---
 
-## Troubleshooting
+### Troubleshooting
 
-### macOS / Linux
+#### macOS / Linux
 
 | Symptom | Fix |
 |---|---|
@@ -372,7 +471,7 @@ Anything outside this whitelist **and** not from the starter template = untouche
 | `Claude Code not installed` after pick | Install Claude Code or pick `[12] Other` to copy the prompt to clipboard |
 | Old Bash on macOS (`bash --version` shows 3.2) | Works — script is Bash 3.2-compatible. If problems, `brew install bash` for Bash 5+ |
 
-### Windows
+#### Windows
 
 | Symptom | Fix |
 |---|---|
@@ -381,7 +480,7 @@ Anything outside this whitelist **and** not from the starter template = untouche
 | `npx` not found in cmd.exe | Open new terminal after Node install (refreshes PATH), or use full path `C:\Program Files\nodejs\npx.cmd` |
 | `pwsh` not found | You have PowerShell 5.1 (built-in) — use the `powershell -ExecutionPolicy Bypass ...` form. To install pwsh 7: `winget install Microsoft.PowerShell` |
 
-### Cross-platform
+#### Cross-platform
 
 | Symptom | Fix |
 |---|---|
@@ -392,7 +491,7 @@ Anything outside this whitelist **and** not from the starter template = untouche
 
 ---
 
-## Suggested reading order (human)
+### Suggested reading order (human)
 
 1. `README.md` (this file) — overview.
 2. `AGENTS.md` — agent master instruction.
@@ -404,7 +503,7 @@ Anything outside this whitelist **and** not from the starter template = untouche
 
 ---
 
-## Quickstart for the agent (after `INIT.md`)
+### Quickstart for the agent (after `INIT.md`)
 
 1. Read `AGENTS.md` (root). That is the contract.
 2. Read `.specs/product/VISION.md` for the why.
@@ -415,7 +514,7 @@ Anything outside this whitelist **and** not from the starter template = untouche
 
 ---
 
-## Optional: clean up starter files
+### Optional: clean up starter files
 
 After the agent finishes `INIT.md`, the bootstrap files are no longer needed.
 
@@ -437,7 +536,7 @@ git add -A; git commit -m "chore: remove starter bootstrap files"
 
 ---
 
-## Companion tooling
+### Companion tooling
 
 - **SkillOpt optimizer** — `npx @wesleysimplicio/llm-project-mapper skillopt --suite <suite.json>` (or `node bin/skillopt.js`) optimizes a `SKILL.md`/prompt with the [SkillOpt](https://microsoft.github.io/SkillOpt/) loop (Rollout → Reflect → Edit → Gate). The skill document is the only trainable artifact; edits are accepted only when they improve a held-out task split. Outputs `best_skill.md` plus an optional report and receipt. See [.skills/skillopt/SKILL.md](.skills/skillopt/SKILL.md).
 - **VS Code extension** — `vscode-extension/` ships a sidebar TreeView for `.specs/sprints/`, plus commands to open the current task, create ADRs, and run the `INIT.md` handoff. See [vscode-extension/README.md](vscode-extension/README.md). Will be published to the Marketplace as `wesleysimplicio.llm-project-mapper-vscode`.
@@ -445,7 +544,7 @@ git add -A; git commit -m "chore: remove starter bootstrap files"
 
 ---
 
-## Philosophy
+### Philosophy
 
 - **Specs as code.** What is not in `.specs/`, the agent does not see.
 - **Atomic tasks.** One task = one small reviewable PR.
@@ -456,16 +555,30 @@ git add -A; git commit -m "chore: remove starter bootstrap files"
 
 ---
 
-## License
+### License
 
 [MIT](LICENSE) © 2026 Wesley Simplicio.
 
 ---
 
-## Next steps
+### Next steps
 
 - Run the bootstrap.
 - Let the agent execute `INIT.md`.
 - Fill specs with real product context (the agent does most of this from the code).
 - Run the first sprint using `.specs/sprints/sprint-01/`.
 - Watch `presentation/ai-agent-specialist.pdf` for the full method.
+
+## Star History
+
+<a href="https://www.star-history.com/#wesleysimplicio/simplicio-mapper&Date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=wesleysimplicio/simplicio-mapper&type=Date&theme=dark" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=wesleysimplicio/simplicio-mapper&type=Date" />
+    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=wesleysimplicio/simplicio-mapper&type=Date" />
+  </picture>
+</a>
+
+## License
+
+MIT. See [LICENSE](LICENSE).