{
  "markdown": "<p align=\"center\">\n  <picture>\n    <source media=\"(prefers-color-scheme: dark)\" srcset=\"./branding/logo-dark.svg\" />\n    <img src=\"./branding/logo.svg\" alt=\"Nowline\" width=\"360\" />\n  </picture>\n</p>\n\n<p align=\"center\">\n  Roadmaps as code. For everyone.<br />\n  <strong>Human readable roadmaps, built for AI.</strong><br />\n  Plain <code>.nowline</code> text files. Version-controlled. Render to SVG, PNG, PDF, HTML, Mermaid, XLSX, and MS Project XML.\n</p>\n\n---\n\n## What is Nowline?\n\nNowline is a text-first DSL for describing product and engineering roadmaps — human readable and machine readable. You write plain `.nowline` text files — indented, keyword-driven, diff-friendly — and tooling renders them as timelines, validates them, and composes them.\n\n[`examples/minimal.nowline`](./examples/minimal.nowline):\n\n```nowline\nnowline v1\n\nroadmap minimal \"Starter\" start:2026-01-05 scale:2w author:\"Jane Doe\"\n\nswimlane engineering \"Engineering\"\n  item research \"Research\"  duration:3w status:done\n  item design   \"Design\"    duration:2w status:in-progress remaining:5d\n  item build    \"Build\"     duration:3w status:planned\n```\n\nRenders to:\n\n<p align=\"center\">\n  <img src=\"./docs/screenshots/minimal.png\" alt=\"Minimal roadmap rendered with light theme and now-line on 2026-02-09\" width=\"720\" />\n</p>\n\n## Why Nowline?\n\n- **Text, not a Gantt chart.** Version-controlled, diffable, reviewable in a PR.\n- **Indentation, not XML.** Roadmaps read like outlines, because that's how people think about them.\n- **Strict enough to catch mistakes.** 30+ validation rules, clear error messages with line and column numbers.\n- **Composable.** `include` other files with explicit `merge` / `ignore` / `isolate` semantics.\n\n## Quick start\n\nInstall the CLI from your package manager:\n\n```bash\nbrew trust lolay/tap                                 # macOS / Linux / WSL (one-time)\nbrew install lolay/tap/nowline\n```\n\nDebian/Ubuntu and Windows users can grab the latest `.deb` or `.exe` from [GitHub Releases](https://github.com/lolay/nowline/releases/latest). See [`packages/cli/README.md`](./packages/cli/README.md#install) for the full install matrix (including `man nowline` setup).\n\n## Toolchain\n\nTwo-tier Node policy: **Node ≥ 22** to **consume** `@nowline/*` packages (`engines.node` on every published package), **Node 26** (`.nvmrc`) to **develop**. CI tests both versions on every PR. See [Toolchain & Supported Versions](./CONTRIBUTING.md#toolchain--supported-versions) for the full policy and bump procedure.\n\nRender your first roadmap:\n\n```bash\nnowline examples/minimal.nowline                     # writes ./minimal.svg\nnowline --version\n```\n\nOr scaffold a brand-new file from a template:\n\n```bash\nnowline --init my-project                            # ./my-project.nowline\nnowline --init my-project -t teams                   # ./my-project.nowline (teams template)\n```\n\nFor the VS Code / Cursor / VSCodium extension, search **Nowline** on the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=nowline.vscode-nowline) or [Open VSX](https://open-vsx.org/extension/nowline/vscode-nowline).\n\n> **`0.x` versioning.** `nowline` is on `0.x.y` while we settle the embed surface and IDE expansion. Public APIs may change between minor versions; full SemVer guarantees apply once we ship `1.0`. See [`specs/releasing.md`](./specs/releasing.md) for the version contract.\n\nTo run from a checkout for local development (`pnpm install && pnpm build`), see [`CONTRIBUTING.md`](./CONTRIBUTING.md).\n\n## Use the CLI\n\n`nowline` is **verbless**: rendering is the default. Other operations are flags on the same command.\n\n### Render (default)\n\n```bash\nnowline roadmap.nowline                          # writes ./roadmap.svg\nnowline roadmap.nowline -f png                   # writes ./roadmap.png\nnowline roadmap.nowline -f pdf                   # writes ./roadmap.pdf\nnowline roadmap.nowline -f html                  # writes ./roadmap.html\nnowline roadmap.nowline -f mermaid               # writes ./roadmap.md\nnowline roadmap.nowline -f xlsx                  # writes ./roadmap.xlsx\nnowline roadmap.nowline -f msproj                # writes ./roadmap.xml\nnowline roadmap.nowline -o roadmap.pdf           # format inferred from extension\nnowline roadmap.nowline -o -                     # SVG to stdout\nnowline roadmap.nowline --theme dark --now 2026-03-15\nnowline roadmap.nowline --now - --asset-root ./brand --no-links --strict\nnowline roadmap.nowline -f pdf --page-size a4 --orientation landscape --margin 0.5in\ncat roadmap.nowline | nowline -                  # stdin → ./roadmap.svg\n```\n\nThe render pipeline is `@nowline/core` parse → `@nowline/layout` layout → `@nowline/renderer` SVG → format-specific exporter. Output is byte-for-byte deterministic for the same input, theme, and `--now`. A single `nowline` binary ships every format — see [`packages/cli/README.md`](./packages/cli/README.md#install) for install details.\n\n### Validate (`--dry-run`)\n\nRun the full pipeline (parse + validate + layout + format) without writing. Exits `0` on success, `1` if any errors are emitted.\n\n```bash\nnowline roadmap.nowline --dry-run\nnowline roadmap.nowline -n                          # short alias\ncat roadmap.nowline | nowline - --dry-run           # read stdin\nnowline roadmap.nowline -n --diagnostic-format json # machine-readable output\n```\n\n### Convert text ↔ JSON\n\nConvert is just `-f json` (or `-f nowline` to go the other way). Input format is inferred from the extension; `--input-format` overrides for unusual filenames.\n\n```bash\nnowline roadmap.nowline -f json -o roadmap.json    # text → JSON\nnowline roadmap.json -f nowline -o roadmap.nowline # JSON → text (canonical)\nnowline roadmap.nowline -f json -o - | jq '.ast.roadmapDecl.name'\n```\n\nThe emitted JSON carries a top-level `\"$nowlineSchema\": \"1\"` so downstream tools can detect schema changes. Comments are not preserved across round-trips — see [`packages/cli/README.md`](./packages/cli/README.md) for the canonical printer rules.\n\n### Serve (`--serve`)\n\nRun a live-reload preview in the browser. Great while authoring.\n\n```bash\nnowline roadmap.nowline --serve                    # http://127.0.0.1:4318\nnowline roadmap.nowline --serve -p 4400 -t dark --open\nnowline roadmap.nowline --serve -o latest.svg      # rewrite latest.svg on each rebuild\n```\n\nThe server re-parses, re-validates, re-lays-out, and re-renders on every file change; connected clients refresh automatically via Server-Sent Events. Validation errors are displayed as an overlay on top of the most recent successful render.\n\n### Init (`--init`)\n\nScaffold a new `.nowline` file in cwd. The positional argument is the **project name**, not a file path. `.nowline` is auto-appended.\n\n```bash\nnowline --init                              # ./roadmap.nowline (default name)\nnowline --init my-project                   # ./my-project.nowline\nnowline --init my-plan.nowline              # ./my-plan.nowline (literal)\nnowline --init my-project --template=teams  # use the teams template\n```\n\n`minimal`, `teams`, and `product` correspond to the files under [`examples/`](./examples). Existing files are silently overwritten.\n\n### Exit codes\n\n| Code | Meaning |\n|---|---|\n| 0 | Success |\n| 1 | Validation error (parse failure, invalid reference) |\n| 2 | Usage error (missing input, bad flags, unsupported format, file not found, binary→TTY refusal) |\n| 3 | Output error (cannot write to destination) |\n\n### Manual\n\nAfter any package-manager install (`brew install lolay/tap/nowline`, `npm install -g @nowline/cli`, or the `.deb` from GitHub Releases), `man nowline` shows the CLI manual and `man 5 nowline` shows the full DSL reference. Both man pages also ship as standalone assets on every [GitHub Release](https://github.com/lolay/nowline/releases) — see [`packages/cli/man/`](./packages/cli/man/) for the mdoc sources.\n\n## Language at a glance\n\n### File structure\n\n```nowline\nnowline v1                        // 1. version directive (optional, must be first)\n\ninclude \"shared/teams.nowline\"    // 2. includes\ninclude \"brand.nowline\" config:isolate\n\nconfig                            // 3. config section (optional)\nscale\n  name: weeks\nstyle enterprise\n  bg: blue\n  fg: navy\n\nroadmap r \"My Roadmap\"            // 4. roadmap section\n\nswimlane platform\n  item x \"Work item\" duration:1w status:done\n```\n\n### Entities\n\n| Keyword | Purpose |\n|---|---|\n| `roadmap` | The top-level roadmap declaration. At most one per file. |\n| `swimlane` | A horizontal lane of work. |\n| `item` | A unit of work inside a swimlane. |\n| `parallel` | A block whose children run concurrently. |\n| `group` | A logical grouping of items, rendered together. |\n| `anchor` | A named date on the timeline. |\n| `milestone` | A point-in-time marker that depends on work. |\n| `footnote` | A callout anchored to one or more entities. |\n| `person`, `team` | Ownership references. |\n| `style`, `label`, `status`, `duration`, `scale`, `calendar`, `default` | Config and declaration entries. |\n\n### Properties\n\n```nowline\nitem auth \"Auth refactor\"\n  duration: 2w              // duration literal: d, w, m, q, y\n  status: in-progress       // builtin or custom from config\n  owner: sam                // id reference (person or team)\n  after: kickoff            // dependency (single)\n  after: [kickoff, approvals] // dependency (list)\n  remaining: 30%             // percentage\n  labels: [security, p0]     // list of label ids\n  link: https://…            // URL (bare, no quotes)\n```\n\n### Roadmap start date\n\nA `roadmap` may carry an optional `start:YYYY-MM-DD` that anchors the timeline baseline:\n\n```nowline\nroadmap platform-2026 \"Platform 2026\" start:2026-01-06\n```\n\n- If the roadmap contains any `anchor`, or any `milestone` with a `date:` property, `start:` is **required**.\n- Every such date must be on or after `start:`.\n- A pure-relative roadmap (built from `duration:` and `after:` only) does not need `start:`.\n- Across `include`s that don't use `roadmap:ignore`, the parent and any included roadmap must agree on `start:` — both absent, or both present with the same value. Mismatches are errors, not silent overrides.\n\n### Includes\n\n```nowline\ninclude \"teams.nowline\"                     // merge everything (default)\ninclude \"snippet.nowline\"  config:ignore    // skip child config\ninclude \"partner.nowline\"  roadmap:isolate  // render child as a separate region\n```\n\n- `merge` — default: child content is merged; parent definitions win on collision.\n- `ignore` — child content of that kind is discarded.\n- `isolate` — child roadmap is preserved as a self-contained region (requires a `roadmap` in the child).\n\nFor the full grammar reference, see [`specs/dsl.md`](./specs/dsl.md).\n\n## Examples\n\nProgressively-richer examples are included:\n\n- [`examples/minimal.nowline`](./examples/minimal.nowline) — smallest complete file.\n- [`examples/capacity.nowline`](./examples/capacity.nowline) — lane and item `capacity:` with on-call support taking a quarter of team bandwidth; lane utilization underline.\n- [`examples/sizing.nowline`](./examples/sizing.nowline) — T-shirt `size:` entries plus shortening calendar span with `capacity:` (parallel work).\n- [`examples/teams.nowline`](./examples/teams.nowline) — persons, teams, anchors, milestones, footnotes.\n- [`examples/product.nowline`](./examples/product.nowline) — full config, styles, labels, parallels, groups, descriptions.\n- [`examples/long.nowline`](./examples/long.nowline) — stress test: eight swimlanes, ~160 items, parallels, groups, anchors, milestones, footnotes, cross-cutting labels. Used for layout/render perf.\n- [`examples/nested.nowline`](./examples/nested.nowline) + [`examples/nested/`](./examples/nested) — parent Security swimlane plus five isolated per-team roadmap includes (iOS, Android, Web, Platform, Data). Demonstrates `roadmap:isolate`.\n\n## Editor support\n\nA TextMate grammar lives at [`grammars/nowline.tmLanguage.json`](./grammars/nowline.tmLanguage.json). It works in any editor that supports TextMate grammars (VS Code, Sublime Text, Zed, IntelliJ via third-party plugins, etc.). A first-class LSP server and VS Code extension are tracked in [`packages/lsp/`](./packages/lsp) and [`packages/vscode-extension/`](./packages/vscode-extension).\n\n## Use as a library\n\n`@nowline/core` is a pure-TypeScript parser, typed AST, and validator built on [Langium](https://langium.org/). Everything the CLI does on top of parsing is itself built against this library. See [`packages/core/README.md`](./packages/core/README.md) for the API and a usage example.\n\n## Status\n\nNowline is on `v0.x` — published to Homebrew, npm, the VS Code Marketplace, Open VSX, and GitHub Releases. The parser, validator, layout, renderer, every export format (SVG, PNG, PDF, HTML, Markdown+Mermaid, XLSX, MS Project XML), and the verbless CLI (`--dry-run`, `--init`, `--serve`) are usable today. Breaking changes may land between `0.x` minor versions while the embed surface and IDE expansion settle; full SemVer guarantees kick in at `1.0`. The release-by-release roadmap lives in [`specs/milestones.md`](./specs/milestones.md).\n\n## Contributing\n\nBug reports, feature requests, and pull requests are welcome. Start with [`CONTRIBUTING.md`](./CONTRIBUTING.md) for setup, build/test commands, and the expected workflow. Before opening an issue, please check the templates under [`.github/ISSUE_TEMPLATE/`](./.github/ISSUE_TEMPLATE). Security issues should follow [`SECURITY.md`](./SECURITY.md). All participation is governed by our [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md).\n\nDesign specs for the DSL, renderer, CLI, IDE integrations, and OSS milestones live under [`specs/`](./specs) — start there to understand how Nowline is shaped before touching code.\n\n## License\n\nApache 2.0 — see [`LICENSE`](./LICENSE).\n",
  "bytes": 13764,
  "sha": "73a64d358fce8c1253a7d70065a5c403e682d92e2995c95acfd3a0a8976985da",
  "repo_slug": "lolay/nowline",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_nowline_nowline_5c2f40be/readme"
}