Metadata-Version: 2.4
Name: navig-text
Version: 0.5.1
Summary: NAVIG Text module — AI text generation (drafts/articles/captions/briefs) + `navig design` (agent HTML/CSS restyle + design tokens) for the Design Mode lens. A first-party navig plugin (free, toggleable). The TEXT facet of the shared media generation engine.
Author-email: NAVIG Development Team <opensource@navig.run>
License-Expression: Apache-2.0
Project-URL: Homepage, https://navig.run
Project-URL: Documentation, https://navig.run/docs
Keywords: navig,cli,agent,automation,plugin,text,ai,generation,design,css,html
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: navig-sdk>=2.8.0
Requires-Dist: typer>=0.14.0
Requires-Dist: rich>=13.7.0
Provides-Extra: media
Requires-Dist: navig-media-core>=0.2.0; extra == "media"
Dynamic: license-file

# navig-text

<!-- navig:plugin-card:start -->
<!-- Generated by scripts/gen_plugin_catalog.py — edit the plugin's pyproject.toml, not this block. -->

> AI text generation (drafts/articles/captions/briefs) + `navig design` (agent HTML/CSS restyle + design tokens) for the Design Mode lens.

**Works on its own** — its own CLI, no navig required · v0.5.1 · [PyPI](https://pypi.org/project/navig-text/)

**On its own** (no navig needed)

```bash
pip install navig-text
navig-text --help   # no navig needed
```

**With navig**

```bash
pip install navig-text
navig text --help
```

<details><summary>Commands</summary>

| Command | What it does |
|---|---|
| `navig design check` | Show whether AI design edits are ready (an AI provider is configured). |
| `navig design edit` | Restyle/rewrite one element per an instruction; print the revised HTML as JSON. |
| `navig design tokens save` | Persist a token set as tokens.json + tokens.css (global, or a space's .navig/design). |
| `navig design tokens show` | Show the stored design tokens (colors, type scale, spacing, radii). |
| `navig text channel data` | The live numbers the cards quote — loud fetch, disk cache, never silently stale. |
| `navig text channel lint` | Check the master against the rules its own header declares. |
| `navig text channel sweep` | Terminology sweep (cities → Zones): literal replacements, reported before written. |
| `navig text channel sync` | Push the master's values into the channel's scripts, positional by structure. |
| `navig text check` | Show whether AI text generation is ready (a provider is configured). |
| `navig text gen` | Generate Markdown text from a prompt and save it locally. |
| `navig text lyrics fit` | 📏 Does a lyric sit on the beat? Syllables per line against the time one bar gives. |
| `navig text lyrics rhyme` | 🎯 Rhymes for a word from the words you already use — spelling-based, strong first. |
| `navig text lyrics scaffold` | 🧱 An empty lyric cut to the beat's measured bar map — one slot per line. |
| `navig text lyrics sheet` | 🗒 A text's hook + its voices table → a sheet for `navig audio beat demo`. |
| `navig text lyrics words` | 🔎 Word-bank entries that mention a term — title hits first. |

</details>

<!-- navig:plugin-card:end -->

AI **text generation** for NAVIG — drafts, articles, captions, and fan-out briefs.
A first-party, free, toggleable plugin, and the **TEXT facet** of NAVIG's shared
media-generation engine.

```bash
navig text gen "explain vector databases in 5 bullets"          # a quick draft
navig text gen "NAVIG weekly update" --kind article --out ./out # a full article
navig text gen "ship faster with NAVIG" --kind caption          # one caption
navig text gen "NAVIG v2 launch" --kind brief                   # a fan-out brief
navig text check                                                # is a provider ready?
```

## `navig text lyrics` — lyrics that sit on a beat

No AI and no network — it reads your files. A beat's bar map comes from its JSON sidecar
(`measured.bars`, written by `navig audio beat gen`); navig-audio is only needed to measure a
beat that has none.

```bash
navig text lyrics scaffold beat.json --lang ru,en,fr -o draft.md   # empty text cut to the measured bar map
navig text lyrics fit draft.md --bpm 88                            # syllables per line vs the bar
navig text lyrics fit --all lyrics/ --beats beats/ --report FIT.md # every text + its nearest beat
navig text lyrics words "hood" --bank lyrics/dictionary            # word-bank entries that mention it
navig text lyrics rhyme night --in lyrics/                         # rhymes from words you already use
navig text lyrics sheet draft.md --beat beat.mp3 --lang fr --start-bar 25 -o demo.yaml
```

- **`scaffold`** maps each measured block to a section — `build` → intro, `drop`/`mid` → hook,
  `full` → 16-line verses (the rest a hook, or a pre-hook pickup), `tail` → outro — and writes
  one `_` slot per line with the syllables it can carry. `fit` never counts a `_` line.
- **`fit`** counts syllables (Russian by vowel, English/French by vowel group) against the time
  one bar gives — about 3.2–5.1 a second — and lists the lines to split, fill or keep as a punch.
  `navig audio beat fit` is an alias.
- **`sheet`** turns a text's first hook and its voices table (`## Voices` / `## Голоса …`: line
  numbers → a voice per language) into a sheet for `navig audio beat demo`.
- **`rhyme`** matches spelling, not sound: strong = same tail from the second-to-last vowel,
  weak = same last vowel and what follows (plus the consonant before an open final vowel).

## `navig design` — the Design Mode surface

The agent-backed surface behind the **Design Mode** browser lens (in the NAVIG
Dock extension). Same core AI client as text generation — code/markup is text, so
it lives here rather than in a separate plugin.

```bash
navig design edit --prompt "make this a bold dark CTA" --html '<button>Buy</button>'
navig design check                                    # is an AI provider ready?
navig design tokens show                              # the global design system
navig design tokens show --space acme                 # a space's design system
```

- `design edit` returns the revised element HTML as JSON on stdout; the lens
  base64-encodes the element + your instruction, calls it via `host.run()`, then
  applies the result live (sanitized) with undo.
- `design tokens save`/`show` persist a page's extracted palette / type scale /
  spacing as `tokens.json` + `tokens.css` under `~/.navig/data/design` (global),
  or into a space's `.navig/design` with `--space <name>` — one design system
  per project.

## How it fits

- **No external deps.** Generation runs through core's AI client
  (`navig.agent.ai_client`) — the architectural law that all inference lives in
  `navig/agent/`. Whatever provider you've connected (`navig connect`) powers it.
- **Registers a facet.** At boot it plugs a `TEXT` backend into the core
  generation registry (`navig.media.types.register_generator`), so
  `navig generate gen --modality text` and the deck media route dispatch through it.
- **Refs-library native.** Generated Markdown lands as `MediaModality.TEXT` rows
  in the same versioned refs library as images / video / audio — so a drafted
  caption or brief flows straight into `navig social fan-out` and the content
  assembly line.

## Install

```bash
pip install -e plugins/navig-text     # dev (editable)
# or, for the user's real CLI:
navig store install pip:navig-text
```

Part of the NAVIG media plugin family: **navig-image · navig-video · navig-audio ·
navig-text** — each a thin facet over one shared engine.
