Metadata-Version: 2.4
Name: furatena
Version: 0.1.1
Summary: Hypermedia documentation catalog for Chirp — live graph, dual IR, fura CLI
Author-email: Bengal Contributors <lbeezr@icloud.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/lbliii/furatena
Project-URL: Repository, https://github.com/lbliii/furatena
Project-URL: Documentation, https://github.com/lbliii/furatena/tree/main/docs
Keywords: documentation,hypermedia,htmx,catalog,chirp,markdown,static-site
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Text Processing :: Markup
Requires-Python: <3.15,>=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bengal-chirp[forms,sessions]<0.10.0,>=0.9.0
Requires-Dist: chirp-ui>=0.11.0
Requires-Dist: cryptography>=46.0.0
Requires-Dist: patitas[syntax]>=0.4.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: jsonschema>=4.0.0
Requires-Dist: idna<4.0,>=3.10
Requires-Dist: milo-cli>=0.4.1
Requires-Dist: reportlab>=5.0.0
Requires-Dist: pypdf>=6.14.2
Requires-Dist: bengal-pounce<0.10.0,>=0.9.2
Provides-Extra: formats
Requires-Dist: docutils>=0.21; extra == "formats"
Provides-Extra: dev
Requires-Dist: docutils>=0.21; extra == "dev"
Requires-Dist: pytest>=9.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-timeout>=2.3; extra == "dev"
Requires-Dist: ruff==0.15.20; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Dynamic: license-file

# Furatena — live documentation from markdown

**Furatena** turns markdown into a documentation site that **updates as you edit** —
with built-in search, navigation, static export, and agent-readable catalog data from
the same corpus.

The CLI is **`fura`** (short for Furatena).

**Under the hood:** markdown is indexed into a queryable graph and served as hypermedia
fragments (htmx) inside a persistent shell — no static rebuild loop, no client framework.
Export to GitHub Pages or feed `/catalog.json` to agents from the same corpus.

## Quick start

From a checkout:

```bash
uv sync --group dev
uv run fura init /tmp/my-docs --name "My Docs"
uv run fura --app-root /tmp/my-docs check --content-only
uv run fura --app-root /tmp/my-docs serve
```

After the package is published to PyPI ([PYPI.md](docs/PYPI.md)):

```bash
pip install furatena
# or: uv tool install furatena
fura init ./my-docs --name "My Docs"
fura --app-root ./my-docs serve
```

`uv run fura serve` is the canonical zero-install command from a checkout. `uv sync`
installs `fura` into the project environment, but does not place a bare `fura` command
on your global shell path. `make serve` and `./app/run` are convenience launchers for
the same CLI path.

To opt into a bare, globally available command backed by this checkout:

```bash
uv tool install --editable .
fura --help
fura serve
```

If the install reports that the uv tool directory is missing from `PATH`, run
`uv tool update-shell`, restart the shell, and retry `fura --help`. Use
`uv tool dir --bin` to inspect the executable directory.

Open http://127.0.0.1:8001/

The default **`app/`** instance dogfoods the Furatena documentation corpus under `content/furatena/`.

## Commands

```bash
uv run fura serve              # hybrid when app/frozen/ exists
uv run fura init ./docs-site   # scaffold a standalone docs app
uv run fura serve --author     # force live index
uv run fura freeze             # catalog IR + HTML + assets → app/frozen/
uv run fura export             # static HTML → app/public/
uv run fura check              # Chirp contracts + corpus lint
uv run fura query --directive tabs
uv run fura migrate --dry-run  # preview MDX → Patitas markdown lowering
uv run fura recipes --json     # stable agent workflow recipes
uv run fura mcp --describe --json
uv run fura author status docs/get-started --json
```

Contributor and CI validation use the same risk-based Make targets. See
[CI lanes](docs/CI.md) for dependencies, scope, and expected runtimes.

## Layout

```
app/           Default deployment (docs.yaml, theme, mounts)
content/       Markdown corpora (content/furatena = default; content/chirp = test fixture)
data/          Collections, glossary, rewrites
config/        Autodoc and shared config
src/furatena/  Library (catalog graph, directives, CLI)
docs/          Furatena design notes (Dual IR, views, roadmap)
tests/         Catalog and runtime tests
```

## Naming

- **Furatena** — the product (from the Muzo legend of Fura and Tena)
- **Fura** — CLI and shorthand
- **Itoco** — internal name for the catalog graph (optional vocabulary)

## Chirp dependency

Furatena depends on the released **`bengal-chirp`** package from PyPI. The supported
runtime line is pinned in `pyproject.toml` (`>=0.9.0,<0.10.0`) so a fresh
`uv sync --group dev` does not depend on any local Chirp checkout.

The production server boundary is also pinned directly to
**`bengal-pounce>=0.9.2,<0.10.0`** so deploys retain structured readiness JSON
during listener drain and complete large buffered responses under downstream
backpressure.

## Docs

- [Dual IR](docs/DUAL_IR.md)
- [Editions and immutable release shards](docs/EDITIONS.md)
- [Views](docs/VIEWS.md)
- [Authoring lifecycle](docs/AUTHORING.md)
- [Author mutation threat model](docs/AUTHOR_MUTATION_THREAT_MODEL.md)
- [Agent workflows](docs/AGENT_WORKFLOWS.md)
- [Agent-readiness score operations](docs/AGENT_SCORE.md)
- [CLI contract](docs/CLI_CONTRACT.md)
- [HTTP QUERY prototype](docs/HTTP_QUERY.md)
- [htmx 4 preview report](docs/HTMX4_PREVIEW.md)
- [Pull-request preview contract](docs/PR_PREVIEW_CONTRACT.md)
- [Hosted preview broker architecture](docs/PREVIEW_BROKER_ARCHITECTURE.md)
- [Hosted preview broker threat model](docs/PREVIEW_BROKER_THREAT_MODEL.md)
- [Railway proprietary template architecture](docs/RAILWAY_TEMPLATE_ARCHITECTURE.md)
- [Live SLOs and no-SSH operations](docs/LIVE_OPERATIONS.md)
- [Compatibility and support policy](docs/COMPATIBILITY.md)
- [Open-source distribution decision](docs/OSS_DISTRIBUTION_DECISION.md)
- [PyPI publishing](docs/PYPI.md)
- [Release and incident runbook](docs/RELEASING.md)
- [CI lanes](docs/CI.md)
- [Roadmap](docs/ROADMAP.md)
