docs: audit release documentation, link benchmarks, and point to GitHub organization #373

Merged

natsukium merged 4 commits from docs-release-audit into main 2026-09-24 01:04:35 +09:00

Conversation 0 Commits 4 Files changed 22 +150 -81

natsukium commented 2026-09-23 23:17:35 +09:00

Owner

Copy link

Summary

Audits and cleans up documentation ahead of public release, integrates the published cross-terminal benchmarks, sharpens the root README's core philosophy and performance profile, and points public repository and schema references to GitHub.

Changes

1. Root README.md Refresh:

   • Articulates felis's core philosophy up front: "A terminal for your toolkit. Not an environment." and "The rest stays yours".
   • Presents macro performance figures across three balanced dimensions drawn directly from the published benchmark suite:
     • Bulk throughput (cat 150MB): ~2.32 s (fastest in the field, ~1.4× faster than Kitty and Foot).
     • Keystroke latency (Typometer / wl-latency): 3.8 ms mean under Wayland, matching Kitty.
     • Idle RSS memory footprint: 32.9 MB (tied with Foot, ~1.6× lighter than Kitty, ~3.6× lighter than WezTerm).
   • Updates quick-start commands to the GitHub flake reference (nix run github:felis-terminal/felis).

2. Documentation Audit & Benchmark Cross-References:

   • Cross-references the newly published benchmark suite (docs/reference/benchmarks.md) in docs/explanation/testing.md, docs/explanation/comparison.md, and docs/explanation/feature-baseline.md.
   • Tightens docs/how-to/update-felis.md by removing redundant lead phrasing.

3. Benchmarking Harness Refinements:

   • In tools/bench/wl-latency/src/main.rs, queries the floating window rectangle under niri so captures are constrained to the terminal under test, preventing active background widgets from interfering with pattern detection.
   • In tools/bench/crossterm.py and suites.py, keeps explicit grid dimensions across font size re-probing so suites compare identical window geometry.

4. Repository, Schema, and Install References to GitHub:

   • Points Cargo.toml repository and nix/package.nix homepage to https://github.com/felis-terminal/felis.
   • Updates compare and tag links in CHANGELOG.md to GitHub.
   • Updates flake inputs, profile installs, and clone commands in docs/how-to/install.md to GitHub references.
   • Updates JSON Schema URLs in docs/reference/cli.md, docs/reference/config.md, and skills/felis/SKILL.md to raw.githubusercontent.com.
   • Regenerates published JSON Schemas (felis-cli-v1.schema.json, felis-bridge-v1.schema.json, felis-json-v1.schema.json) with the updated $id and $ref bases via just schema.

Verification

• just check passes cleanly (nextest workspace, clippy, treefmt, cargo-deny bans/advisories/licenses/sources, proto-compat 66/66, release-verify self-test).
• just prose-check passes with 0 violations.
• just docs-links and lychee --offline README.md pass with 0 broken links.
• just bench-vs-selftest passes all 204 tests.

## Summary Audits and cleans up documentation ahead of public release, integrates the published cross-terminal benchmarks, sharpens the root README's core philosophy and performance profile, and points public repository and schema references to GitHub. ### Changes 1. **Root `README.md` Refresh:** - Articulates felis's core philosophy up front: *"A terminal for your toolkit. Not an environment."* and *"The rest stays yours"*. - Presents macro performance figures across three balanced dimensions drawn directly from the published benchmark suite: - **Bulk throughput (`cat 150MB`):** ~2.32 s (fastest in the field, ~1.4× faster than Kitty and Foot). - **Keystroke latency (Typometer / wl-latency):** 3.8 ms mean under Wayland, matching Kitty. - **Idle RSS memory footprint:** 32.9 MB (tied with Foot, ~1.6× lighter than Kitty, ~3.6× lighter than WezTerm). - Updates quick-start commands to the GitHub flake reference (`nix run github:felis-terminal/felis`). 2. **Documentation Audit & Benchmark Cross-References:** - Cross-references the newly published benchmark suite (`docs/reference/benchmarks.md`) in `docs/explanation/testing.md`, `docs/explanation/comparison.md`, and `docs/explanation/feature-baseline.md`. - Tightens `docs/how-to/update-felis.md` by removing redundant lead phrasing. 3. **Benchmarking Harness Refinements:** - In `tools/bench/wl-latency/src/main.rs`, queries the floating window rectangle under niri so captures are constrained to the terminal under test, preventing active background widgets from interfering with pattern detection. - In `tools/bench/crossterm.py` and `suites.py`, keeps explicit grid dimensions across font size re-probing so suites compare identical window geometry. 4. **Repository, Schema, and Install References to GitHub:** - Points `Cargo.toml` repository and `nix/package.nix` homepage to `https://github.com/felis-terminal/felis`. - Updates compare and tag links in `CHANGELOG.md` to GitHub. - Updates flake inputs, profile installs, and clone commands in `docs/how-to/install.md` to GitHub references. - Updates JSON Schema URLs in `docs/reference/cli.md`, `docs/reference/config.md`, and `skills/felis/SKILL.md` to `raw.githubusercontent.com`. - Regenerates published JSON Schemas (`felis-cli-v1.schema.json`, `felis-bridge-v1.schema.json`, `felis-json-v1.schema.json`) with the updated `$id` and `$ref` bases via `just schema`. ### Verification - `just check` passes cleanly (nextest workspace, clippy, treefmt, cargo-deny bans/advisories/licenses/sources, proto-compat 66/66, release-verify self-test). - `just prose-check` passes with 0 violations. - `just docs-links` and `lychee --offline README.md` pass with 0 broken links. - `just bench-vs-selftest` passes all 204 tests.

natsukium added 4 commits 2026-09-23 23:17:35 +09:00

docs: link published benchmark results and tighten update guide ... 46955e64af

Commit 140a1a18 added docs/reference/benchmarks.md, but the owning
explanation docs (testing strategy, peer comparison, and feature
baseline) did not point to the published measurements. Adding these
links fulfills the Diátaxis twin rule and anchors the boundary decisions
without repeating reference facts in explanation prose.

Also prune a redundant sentence at the end of the package manager
section in how-to/update-felis.md that restated what the lead section
already says.

docs: articulate performance and protocol fidelity in root README ... bc0e9a467b

Connect felis's core design philosophy (a terminal for your toolkit,
not an environment) to its engineering outcomes: top-tier bulk
throughput, low keystroke latency, and an idle footprint under 33 MB,
demonstrated in cross-terminal benchmarks against Kitty, Alacritty,
WezTerm, and Ghostty.

Also update the quick start to use github:felis-terminal/felis for
clearer public release onboarding.

bench: isolate window rectangle and preserve explicit grid under tiling desktops ... 55cb95bd44

Measuring latency under niri with whole-output captures lets other active
desktop elements compete with the inserted pattern for the busiest row.
Constraining the diff to the floating window's rectangle keeps the
detection focused on the measured terminal. In the orchestrator, keep an
explicit grid parameter across font re-probing so comparison suites share
one consistent window area.

treewide: point repository, schema, and install URLs to GitHub organization ... 89b679230c

felis is being published to the public GitHub repository at
https://github.com/felis-terminal/felis. Point the cargo and nix
metadata, changelog compare links, installation guides, published JSON
schemas ($id and $ref), and editor schema reference comments to the
public repository and raw GitHub URLs so external users and schema
validators resolve against the public origin. Forgejo issue tracker
links remain pointed to the project's issue forge.

natsukium merged commit a4f744df0d into main 2026-09-24 01:04:35 +09:00

natsukium deleted branch docs-release-audit 2026-09-24 01:04:35 +09:00

natsukium referenced this pull request from a commit 2026-09-24 01:04:37 +09:00

docs: audit release documentation, link benchmarks, and point to GitHub organization (#373)

Commenting is not possible because the repository is archived.

Reviewers

No reviewers

Labels

Clear labels   

priority/P0

Must be resolved before the v0.1.0 tag

  

priority/P1

Must be settled before the first public contract freezes

  

priority/P2

Explicitly deferred until after v0.1.0

  

release/v0.1.0

Work tracked for the first tagged release

  

status/blocked

Cannot start now: waits on an upstream release, another issue, or a recorded revisit trigger

  

status/planned

Triaged with a source-grounded plan and a passed pi review; ready to implement

  

type/bug

Shipped behavior that contradicts the docs or the code's own intent; needs a product code change

  

type/design

An open scope or trade-off question; needs a recorded decision in the owning explanation doc before code

  

type/test-gap

Documented or reviewed behavior that no test pins; usually split from a review finding, needs no product code change

  

type/tracker

Parent issue that tracks child work

No labels

priority/P0

priority/P1

priority/P2

release/v0.1.0

status/blocked

status/planned

type/bug

type/design

type/test-gap

type/tracker

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

natsukium/felis!373

No description provided.