Skip to content

docs: shorten the README hero, add key features and a one-prompt quickstart - #34

Merged
nvquanghuy merged 8 commits into
mainfrom
docs/readme-features
Oct 11, 2026
Merged

nvquanghuy merged 8 commits into
mainfrom
docs/readme-features

Conversation

@nvquanghuy

@nvquanghuy nvquanghuy commented Oct 10, 2026 •

Copy link
Copy Markdown
Collaborator

Follow-up to #26.

Hero

  • Tagline now matches the repo description and the social preview image: "Open-source framework for building trusted custom BI apps". The previous taglines are kept in an HTML comment as alternatives.
  • The intro paragraphs move out of the hero into a new "What is anfra?" section after the demo image, so the image shows without scrolling.
  • Adds "Built by the team behind Holistics and dbdiagram.io." under the links.

Key features

A new section after "Why anfra?", split by audience:

  • For data teams: metrics defined once as code, every number can be inspected, your warehouse and infrastructure.
  • For people building and using apps: any layout, interactions built in, live data.

Quickstart

  • Adds "Fastest start: one prompt" at the top: a prompt to paste into Claude Code, Codex or Cursor that installs anfra, connects the reader's database (they enter credentials themselves), models a few tables, builds a first app and runs the server. The manual steps follow under "Or step by step".
  • Step 1 mentions --agent cursor and npx skills add holistics/anfra-skills for other agents.
  • Step 2 now says what anfra init creates: the models/, datasets/ and apps/ folders and .anfra/data_sources.yml, which is added to .gitignore. The setup-repo prompt in that step is dropped, since the one-prompt start covers it.

Name

The product name is written as lowercase "anfra" throughout the README, matching the logo. In-page anchors are unchanged.

🤖 Generated with Claude Code

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request updates the README.md to use lowercase branding for "anfra" and adds sections on key features and team background. The reviewer feedback highlights several grammatical issues where sentences incorrectly start with a lowercase letter due to this branding change, and offers rephrasing suggestions to maintain proper capitalization.

Comment thread README.md Outdated
## Why Anfra?
## What is anfra?

Build with AI coding agents using your own HTML, JavaScript, and charting libraries. anfra SDK connects your app to a governed semantic foundation with consistent, reusable metrics and trusted business context.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Starting a sentence with a lowercase letter is grammatically incorrect. To respect the lowercase branding of anfra while maintaining proper sentence capitalization, we can rephrase the sentence slightly.

Suggested change
Build with AI coding agents using your own HTML, JavaScript, and charting libraries. anfra SDK connects your app to a governed semantic foundation with consistent, reusable metrics and trusted business context.
Build with AI coding agents using your own HTML, JavaScript, and charting libraries. The anfra SDK connects your app to a governed semantic foundation with consistent, reusable metrics and trusted business context.

Comment thread README.md
## How anfra works

Anfra sits between your app and your semantic layer. It isn't a semantic layer itself: the SDK runs in your page, and the server turns each click into a query on the metrics your semantic layer defines.
anfra sits between your app and your semantic layer. It isn't a semantic layer itself: the SDK runs in your page, and the server turns each click into a query on the metrics your semantic layer defines.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Starting a sentence with a lowercase letter is grammatically incorrect. To respect the lowercase branding of anfra while maintaining proper sentence capitalization, we can rephrase the sentence slightly.

Suggested change
anfra sits between your app and your semantic layer. It isn't a semantic layer itself: the SDK runs in your page, and the server turns each click into a query on the metrics your semantic layer defines.
The anfra framework sits between your app and your semantic layer. It isn't a semantic layer itself: the SDK runs in your page, and the server turns each click into a query on the metrics your semantic layer defines.

Comment thread README.md
- **anfra Server** (`anfra serve`): serves your apps, takes each request from the SDK, turns the interaction (a filter, a drill-down, a comparison) into a query on your semantic layer, runs it on the warehouse, and returns the results. It also serves MCP so coding agents can read your models.

Anfra runs on **your semantic layer**: your models, datasets, and metrics, defined as code. Anfra ships with [AMQL](https://amql.org) built in. Support for external semantic layers such as dbt, Cube, Snowflake and Databricks is planned ([details](#faq)).
anfra runs on **your semantic layer**: your models, datasets, and metrics, defined as code. anfra ships with [AMQL](https://amql.org) built in. Support for external semantic layers such as dbt, Cube, Snowflake and Databricks is planned ([details](#faq)).

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Starting a sentence with a lowercase letter is grammatically incorrect. To respect the lowercase branding of anfra while maintaining proper sentence capitalization, we can rephrase the sentence slightly.

Suggested change
anfra runs on **your semantic layer**: your models, datasets, and metrics, defined as code. anfra ships with [AMQL](https://amql.org) built in. Support for external semantic layers such as dbt, Cube, Snowflake and Databricks is planned ([details](#faq)).
The framework runs on **your semantic layer**: your models, datasets, and metrics, defined as code. It ships with [AMQL](https://amql.org) built in. Support for external semantic layers such as dbt, Cube, Snowflake and Databricks is planned ([details](#faq)).

Comment thread README.md
```

**3. A user clicks "APAC".** Anfra Server adds the filter to the trend query and runs this SQL (PostgreSQL, with time zone handling trimmed):
**3. A user clicks "APAC".** anfra Server adds the filter to the trend query and runs this SQL (PostgreSQL, with time zone handling trimmed):

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Starting a sentence with a lowercase letter is grammatically incorrect. To respect the lowercase branding of anfra while maintaining proper sentence capitalization, we can rephrase the sentence slightly.

Suggested change
**3. A user clicks "APAC".** anfra Server adds the filter to the trend query and runs this SQL (PostgreSQL, with time zone handling trimmed):
**3. A user clicks "APAC".** The anfra Server adds the filter to the trend query and runs this SQL (PostgreSQL, with time zone handling trimmed):

Comment thread README.md Outdated
## anfra OSS vs anfra Cloud

Anfra Cloud is our hosted product, built on the same open-source engine. It adds what a team needs to share apps: users and SSO, row-level permissions, hosted apps with sharing links, audit logs and version history.
anfra Cloud is our hosted product, built on the same open-source engine. It adds what a team needs to share apps: users and SSO, row-level permissions, hosted apps with sharing links, audit logs and version history.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Starting a sentence with a lowercase letter is grammatically incorrect. To respect the lowercase branding of anfra while maintaining proper sentence capitalization, we can rephrase the sentence slightly.

Suggested change
anfra Cloud is our hosted product, built on the same open-source engine. It adds what a team needs to share apps: users and SSO, row-level permissions, hosted apps with sharing links, audit logs and version history.
Our hosted product, anfra Cloud, is built on the same open-source engine. It adds what a team needs to share apps: users and SSO, row-level permissions, hosted apps with sharing links, audit logs and version history.

Comment thread README.md
<summary><b>How is this different from Streamlit, Evidence or Hex?</b></summary>

Those give you a framework to write the app in. Anfra gives you a semantic backend for any front end the agent writes: plain HTML/JS, no Python runtime, no fixed component set. Metrics and interactions are defined once and shared across every app.
Those give you a framework to write the app in. anfra gives you a semantic backend for any front end the agent writes: plain HTML/JS, no Python runtime, no fixed component set. Metrics and interactions are defined once and shared across every app.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Starting a sentence with a lowercase letter is grammatically incorrect. To respect the lowercase branding of anfra while maintaining proper sentence capitalization, we can rephrase the sentence slightly.

Suggested change
Those give you a framework to write the app in. anfra gives you a semantic backend for any front end the agent writes: plain HTML/JS, no Python runtime, no fixed component set. Metrics and interactions are defined once and shared across every app.
Those give you a framework to write the app in. In contrast, anfra gives you a semantic backend for any front end the agent writes: plain HTML/JS, no Python runtime, no fixed component set. Metrics and interactions are defined once and shared across every app.

Comment thread README.md Outdated
<summary><b>I already have a BI tool. Why would I switch?</b></summary>

Anfra is built to replace dashboard BI tools, not to sit beside them. Those tools were designed for building reports by hand in a fixed grid of charts and filters. With a coding agent, your team can build the app they actually need, and Anfra keeps it governed: metrics are defined once in the semantic layer, and every number can be inspected back to its query and definition. Anfra Cloud adds users, permissions and sharing.
anfra is built to replace dashboard BI tools, not to sit beside them. Those tools were designed for building reports by hand in a fixed grid of charts and filters. With a coding agent, your team can build the app they actually need, and anfra keeps it governed: metrics are defined once in the semantic layer, and every number can be inspected back to its query and definition. anfra Cloud adds users, permissions and sharing.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Starting a sentence with a lowercase letter is grammatically incorrect. To respect the lowercase branding of anfra while maintaining proper sentence capitalization, we can rephrase the sentence slightly.

Suggested change
anfra is built to replace dashboard BI tools, not to sit beside them. Those tools were designed for building reports by hand in a fixed grid of charts and filters. With a coding agent, your team can build the app they actually need, and anfra keeps it governed: metrics are defined once in the semantic layer, and every number can be inspected back to its query and definition. anfra Cloud adds users, permissions and sharing.
We built anfra to replace dashboard BI tools, not to sit beside them. Those tools were designed for building reports by hand in a fixed grid of charts and filters. With a coding agent, your team can build the app they actually need, and anfra keeps it governed: metrics are defined once in the semantic layer, and every number can be inspected back to its query and definition. anfra Cloud adds users, permissions and sharing.

Comment thread README.md
<summary><b>Can I use my existing semantic layer?</b></summary>

Not today. Anfra ships with AMQL. We plan to support other semantic layers such as Cube, dbt, Snowflake and Databricks, though advanced interactions like funnels and period comparisons will depend on AMQL.
Not today. anfra ships with AMQL. We plan to support other semantic layers such as Cube, dbt, Snowflake and Databricks, though advanced interactions like funnels and period comparisons will depend on AMQL.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Starting a sentence with a lowercase letter is grammatically incorrect. To respect the lowercase branding of anfra while maintaining proper sentence capitalization, we can rephrase the sentence slightly.

Suggested change
Not today. anfra ships with AMQL. We plan to support other semantic layers such as Cube, dbt, Snowflake and Databricks, though advanced interactions like funnels and period comparisons will depend on AMQL.
Not today. The anfra platform ships with AMQL. We plan to support other semantic layers such as Cube, dbt, Snowflake and Databricks, though advanced interactions like funnels and period comparisons will depend on AMQL.

Comment thread README.md
<summary><b>Does my data leave my warehouse? Which AI does anfra use?</b></summary>

Queries run on your warehouse, and the Anfra server sends results straight to the page. Apps don't store query results or warehouse credentials by default. Anfra doesn't include an AI model: you use your own coding agent, so what the agent can see depends on what you connect it to.
Queries run on your warehouse, and the anfra server sends results straight to the page. Apps don't store query results or warehouse credentials by default. anfra doesn't include an AI model: you use your own coding agent, so what the agent can see depends on what you connect it to.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Starting a sentence with a lowercase letter is grammatically incorrect. To respect the lowercase branding of anfra while maintaining proper sentence capitalization, we can rephrase the sentence slightly.

Suggested change
Queries run on your warehouse, and the anfra server sends results straight to the page. Apps don't store query results or warehouse credentials by default. anfra doesn't include an AI model: you use your own coding agent, so what the agent can see depends on what you connect it to.
Queries run on your warehouse, and the anfra server sends results straight to the page. Apps don't store query results or warehouse credentials by default. The platform doesn't include an AI model: you use your own coding agent, so what the agent can see depends on what you connect it to.

Comment thread README.md
<summary><b>How does anfra relate to Holistics? Will I be locked in?</b></summary>

Anfra is built by the team behind Holistics, and AMQL is the semantic layer Holistics runs on. Anfra is a separate open-source project, licensed under Apache 2.0, and doesn't need a Holistics account. Your models and apps are plain files in your own repository, and AMQL compiles to SQL you can read.
anfra is built by the team behind Holistics, and AMQL is the semantic layer Holistics runs on. anfra is a separate open-source project, licensed under Apache 2.0, and doesn't need a Holistics account. Your models and apps are plain files in your own repository, and AMQL compiles to SQL you can read.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Starting a sentence with a lowercase letter is grammatically incorrect. To respect the lowercase branding of anfra while maintaining proper sentence capitalization, we can rephrase the sentence slightly.

Suggested change
anfra is built by the team behind Holistics, and AMQL is the semantic layer Holistics runs on. anfra is a separate open-source project, licensed under Apache 2.0, and doesn't need a Holistics account. Your models and apps are plain files in your own repository, and AMQL compiles to SQL you can read.
The team behind Holistics built anfra, and AMQL is the semantic layer Holistics runs on. As a separate open-source project licensed under Apache 2.0, anfra doesn't need a Holistics account. Your models and apps are plain files in your own repository, and AMQL compiles to SQL you can read.

@nvquanghuy nvquanghuy changed the title docs: shorten the README hero, add key features, and lowercase anfra docs: shorten the README hero, add key features and a one-prompt quickstart Oct 10, 2026
nvquanghuy and others added 6 commits October 11, 2026 15:36
Move the intro paragraphs under a "What is Anfra?" section after the
demo image, match the tagline to the repo description, and credit the
team behind Holistics and dbdiagram.io. Add a key features list split
by audience, and say what anfra init creates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Put a prompt at the top of the Quickstart that sets up anfra and builds
a first app on the reader's own data, and nest the manual steps under
it. Mention npx skills add for agents other than Claude Code and Codex,
and drop the setup-repo prompt that the new prompt replaces.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Model only what the chosen app needs instead of guessing at core
tables, and suggest apps from the schema when the reader has none in
mind.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Mark Cloud as coming soon in the heading and table, describe it in
future tense, and replace the unlinked waitlist line.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@nvquanghuy
nvquanghuy force-pushed the docs/readme-features branch from 9072830 to 5a16bfc Compare October 11, 2026 08:36
nvquanghuy and others added 2 commits October 11, 2026 15:44
Drop the alternative-tagline and GIF TODO comments, italicize the
"Built by" line, and bold the definition at the start of What is
anfra.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Replace the one-line "Built by" credit under the tagline with an About
the team section before the license, covering Holistics, dbdiagram.io,
dbdocs.io and DBML, with figures from their public sites.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@nvquanghuy
nvquanghuy merged commit 5230830 into main Oct 11, 2026
7 checks passed
@nvquanghuy
nvquanghuy deleted the docs/readme-features branch October 11, 2026 09:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants