For Coding Agents¶

Prescriptive reference for agents. Two audiences: agents that build a site on the theme (sections marked site) and agents that change the theme in iscc/zensical-iscc (marked theme). Everything else applies to both. Full Markdown of this site: llms-full.txt.

Architecture map¶

Package layout (theme)¶

Import flow¶

cli → check → markdown, project, project_logo
cli → markdown, project, project_logo
project_logo → zensical_iscc.THEME_DIR, fontTools

Public surface¶

Decision dispatch¶

Which command (site)¶

Which setting (site)¶

Where a theme change goes (theme)¶

Constraints and invariants¶

Side effects catalog¶

Task recipes¶

Put a site on the theme (site)¶

1. Follow skills/iscc-docs-theme/SKILL.md; it covers survey, questions for the human, dependency, config, cleanup, CI and verification.
2. Dependency: docs = ["zensical-iscc"] and zensical-iscc = { git = "https://github.com/iscc/zensical-iscc", tag = "vX.Y.Z" } in [tool.uv.sources].
3. Copy this repository's zensical.toml; replace values marked # site.
4. Every page: icon: lucide/<name> and description: in front matter.
5. Write docs/for-coding-agents.md with /zensical-iscc:docs-for-agents create; add { "For Coding Agents" = "for-coding-agents.md" } as the last nav entry.
6. uv run zensical-iscc build && uv run zensical-iscc check --strict → 0 errors, 0 warnings.

Add a check (theme)¶

def thing_findings(config):
    # type: (dict) -> list[tuple[str, str]]
    """Check ..."""
    if problem:
        return [warning("set `x` in [project.extra.iscc]: why it matters")]
    return []

Then call it in check.check(), add tests in tests/test_check.py, list the finding in docs/command-line.md, and the setting in docs/configuration.md and skills/iscc-docs-theme/SKILL.md.

Upgrade Zensical (theme)¶

1. Bump zensical== in pyproject.toml; uv lock.
2. uv run poe docs; compare both schemes at phone, desktop and wide widths with the previous version.
3. uv run poe ci; test_header_is_zensicals_plus_the_projects_menu fails if Zensical's header changed.
4. Add a CHANGELOG.md entry naming the pinned version.

Release (theme)¶

Only when the human asks: rename "Unreleased" in CHANGELOG.md, set version in pyproject.toml and skills/.claude-plugin/plugin.json (tests/test_plugin.py keeps them equal), commit, then git tag vX.Y.Z && git push origin vX.Y.Z and gh release create vX.Y.Z --notes "...".

Change playbook¶

Common mistakes¶

NEVER build a deployable site with zensical build. ALWAYS use zensical-iscc build; otherwise "Copy page", llms.txt and the project logo are missing and check reports errors.

NEVER set font, logo, favicon or palette in [project.theme], and NEVER add navigation.instant to features. The theme serves its own fonts and marks; instant navigation makes lightbox pages fetch GLightbox from unpkg.com.

NEVER put main.html or a copy of the theme in a site's custom_dir.

<!-- WRONG: docs/overrides/main.html replaces the theme's -->
{% extends "base.html" %}
<!-- RIGHT: docs/overrides/landing.html, selected with `template: landing.html` -->
{% extends "main.html" %}

NEVER hot-link images or badges (https://img.shields.io/...). ALWAYS store a copy under docs/.

NEVER use fenced mermaid blocks. The bundle would load Mermaid from unpkg.com; check rejects the page.

NEVER write [project.extra.iscc.related] with single brackets, and NEVER put nav = [...] after a table header.

# WRONG
[project.extra.iscc]
nav = [{ "Home" = "index.md" }]     # now project.extra.iscc.nav
# RIGHT
[project]
nav = [{ "Home" = "index.md" }]

NEVER override a Zensical rule in theme.css with a less specific selector. ALWAYS match the original, including :not() arguments, which add their own weight.

/* WRONG: loses to Zensical's `html .md-footer-meta.md-typeset a:not(:focus, :hover)` */
.md-footer-meta a { color: var(--md-footer-fg-color); }
/* RIGHT */
html .md-footer-meta.md-typeset a:not(:focus, :hover) { color: var(--md-footer-fg-color--light); }

NEVER read page.meta.x in a template without a guard. ALWAYS {% set meta = page.meta or {} %} first; MiniJinja raises on attribute access of an undefined value. page.is_homepage is unreliable: also test page.url == "".

NEVER edit docs/changelog.md, tokens/, fonts/, logos/, vendor/ or skills/docs-for-agents/SKILL.md in this repository. They are copies; change the source.

NEVER let this page drift. ALWAYS run /zensical-iscc:docs-for-agents update after changing the public API, the command line or the configuration.