Skip to content

docs(skills): make the analytics dataset a module-completeness line item#13972

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
os-zhuang merged 1 commit into from
Sep 1, 2026
+28 −5
Merged

docs(skills): make the analytics dataset a module-completeness line item #13972

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions content/docs/getting-started/build-with-claude-code.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -356,16 +356,24 @@ prompt you can give verbatim:
|:---|:---|:---|
| Data model — objects, fields, relationships, validations, seeds | `objectstack-data` | "Add an `account` object and link tickets to it with a required lookup. Seed three demo accounts." |
| Queries & reports over records | `objectstack-query` | "Show me the count of open tickets per priority, using an aggregation." |
| Views, dashboards, apps, record pages | `objectstack-ui` | "Add a dashboard with a metric for open tickets and a bar chart of tickets by priority." |
| Views, dashboards, apps, record pages | `objectstack-ui` | "Declare a `tickets` dataset over the ticket object, then add a dashboard with a metric for open tickets and a bar chart of tickets by priority." |
| Business automation — flows, approvals, schedules | `objectstack-automation` | "Every day at 9:00, escalate tickets that have been open more than 48 hours." |
| Permissions & row-level security | `objectstack-data` (security sections) | "Members should only see their own tickets; support managers see everything." |
| Formula / conditional-field logic (CEL) | `objectstack-formula` | "Make `resolved_at` required and visible only when status is resolved." |
| AI agents & tools inside your app | `objectstack-ai` | "Add an AI skill that triages new tickets into a priority." |
| REST/auth surface tuning | `objectstack-api` | "Restrict the ticket API to read-only for non-members." |
| Translations | `objectstack-i18n` | "Add a zh-CN translation bundle for the ticket object and app navigation." |

Two habits keep this reliable as the app grows:
Three habits keep this reliable as the app grows:

- **A module is not finished until its analytics face exists.** Objects, views
and a nav entry make an object usable; they do not make it *reportable*.
Dashboards and reports bind a **declared dataset** by name
(`src/datasets/*.dataset.ts`) — the layer that carries the governed joins,
filters and measure definitions an object does not express — so an object with
no dataset simply never appears in the report builder. Ask for the dataset in
the same breath as the views, and `objectstack-ui`'s completeness blueprint
lists it as its own line item.
- **The gate applies to every domain.** Flows, dashboards, permissions, and
translations all go through the same `npm run validate` — the agent should run
it after each change, exactly as `AGENTS.md` instructs.
Expand Down
16 changes: 15 additions & 1 deletion scripts/check-skills-token-ratchet.mjs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -272,7 +272,21 @@ export const CEILINGS = new Map([
// minimal anchor form; the raising PR's body carries the arithmetic.
['skills/objectstack-pm-dispatch/SKILL.md', 14391],
['skills/objectstack-query/SKILL.md', 5552], // -17 (was 5569)
['skills/objectstack-ui/SKILL.md', 25125], // -29 (was 25154)
// 25125 -> 25143: the CRM UI Blueprint — the catalog's module-completeness
// list, and the only place an agent is told what a finished module contains —
// priced `src/views/**`, `src/apps/**`, dashboards and reports but never the
// DATASET those last two bind, so an agent grew the app face and left the
// analytics face silently empty (a module shipped with views, nav, approvals
// and permissions was simply absent from the report builder). Maintainer
// ruling 2026-08-31, director seat batch #15, verbatim and untranslated:
// 「同意」 — accepting option C, whose text is: 「发布技能与文档的「长模块」路径
// 必须把 dataset 声明列为模块完整性的一部分」. Arithmetic, in bytes because that
// is what this convention divides: +204 for the new blueprint row, -7 for the
// Reports row it lets shrink, and -77 for a sentence deleted in the same file
// that restated report binding a second time inside its own paragraph — +120
// net, 25113 -> 25143 tokens. The row's 12 tokens of headroom absorb part of
// it, so the CEILING moves 18. The raising PR's body carries the same numbers.
['skills/objectstack-ui/SKILL.md', 25143],
['skills/objectstack-upgrade/SKILL.md', 8333], // -2 (was 8335)

// ── the #12392 extension: the rest of the AUTHORED bundle ────────────────
Expand Down
5 changes: 3 additions & 2 deletions skills/objectstack-ui/SKILL.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -688,7 +688,7 @@ allowed joins, intrinsic filter, dimensions, and certified measures. The legacy
per-widget inline query (`object` + `categoryField` + `valueField` + `aggregate`)
**was removed** — a widget now requires `dataset` + `values`; the closed schema
REJECTS the inline keys by name, and one lacking `dataset` fails `os validate`.
Reports bind the same way (`dataset` + `rows` + `values` + `runtimeFilter`). The dataset shape is
The dataset shape is
`DatasetSchema` — see `node_modules/@objectstack/spec/src/ui/dataset.zod.ts`.

A widget's presentation-scope `filter` flows into the query as the runtime
Expand DownExpand Up@@ -1404,8 +1404,9 @@ Use this CRM-style structure as the canonical UI assembly reference:
| Multi-view object UI | `src/views/*.view.ts` | Define default `list` + `form`, then named `listViews` / `formViews` for scenarios |
| **Public / anonymous form** | `src/views/*.view.ts` (formView with `sharing.allowAnonymous: true`) | Web-to-Lead / Web-to-Case. Auto-exposed at `GET/POST /api/v1/forms/:slug` |
| App navigation | `src/apps/*.app.ts` | Use grouped nav trees, `viewName` shortcuts, and `requiresObject` for capability-aware visibility |
| **Analytics dataset** | `src/datasets/*.dataset.ts` | One per object you want reportable — dashboards and reports bind a **declared** dataset by name, so an object without one has no analytics face |
| Dashboards | `src/dashboards/*.dashboard.ts` | Combine KPI + chart + table widgets with shared `dateRange` and `globalFilters` |
| Reports | `src/reports/*.report.ts` | Bind a `dataset` + `rows` (dimensions) + `values` (measures) for tabular/summary/matrix/joined analytics |
| Reports | `src/reports/*.report.ts` | Select `rows` (dimensions) + `values` (measures) from that dataset; tabular/summary/matrix/joined |
| Record pages | `src/pages/*.page.ts` | Compose `regions` + components (`page:header`, `record:highlights`, related lists, tabs) |
| User actions | `src/actions/*.actions.ts` | Use `flow` for orchestration and `modal` for parameterized bulk mutations |

Expand Down
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all 
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
docs(skills): make the analytics dataset a module-completeness line item by claude[bot] · Pull Request #13972 · objectstack-ai/objectstack · GitHub
Skip to content
docs(skills): make the analytics dataset a module-completeness line item#13972

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-zhuang
merged 1 commit into

from

Sep 1, 2026

+28

−5

 Merged


docs(skills): make the analytics dataset a module-completeness line item
#13972
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


12 changes: 10 additions & 2 deletions
content/docs/getting-started/build-with-claude-code.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -356,16 +356,24 @@ prompt you can give verbatim:
|:---|:---|:---|
| Data model — objects, fields, relationships, validations, seeds | `objectstack-data` | "Add an `account` object and link tickets to it with a required lookup. Seed three demo accounts." |
| Queries & reports over records | `objectstack-query` | "Show me the count of open tickets per priority, using an aggregation." |
| Views, dashboards, apps, record pages | `objectstack-ui` | "Add a dashboard with a metric for open tickets and a bar chart of tickets by priority." |
| Views, dashboards, apps, record pages | `objectstack-ui` | "Declare a `tickets` dataset over the ticket object, then add a dashboard with a metric for open tickets and a bar chart of tickets by priority." |
| Business automation — flows, approvals, schedules | `objectstack-automation` | "Every day at 9:00, escalate tickets that have been open more than 48 hours." |
| Permissions & row-level security | `objectstack-data` (security sections) | "Members should only see their own tickets; support managers see everything." |
| Formula / conditional-field logic (CEL) | `objectstack-formula` | "Make `resolved_at` required and visible only when status is resolved." |
| AI agents & tools inside your app | `objectstack-ai` | "Add an AI skill that triages new tickets into a priority." |
| REST/auth surface tuning | `objectstack-api` | "Restrict the ticket API to read-only for non-members." |
| Translations | `objectstack-i18n` | "Add a zh-CN translation bundle for the ticket object and app navigation." |

Two habits keep this reliable as the app grows:
Three habits keep this reliable as the app grows:

- **A module is not finished until its analytics face exists.** Objects, views
 and a nav entry make an object usable; they do not make it *reportable*.
 Dashboards and reports bind a **declared dataset** by name
 (`src/datasets/*.dataset.ts`) — the layer that carries the governed joins,
 filters and measure definitions an object does not express — so an object with
 no dataset simply never appears in the report builder. Ask for the dataset in
 the same breath as the views, and `objectstack-ui`'s completeness blueprint
 lists it as its own line item.
- **The gate applies to every domain.** Flows, dashboards, permissions, and
 translations all go through the same `npm run validate` — the agent should run
 it after each change, exactly as `AGENTS.md` instructs.
Expand Down

16 changes: 15 additions & 1 deletion
scripts/check-skills-token-ratchet.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -272,7 +272,21 @@ export const CEILINGS = new Map([
 // minimal anchor form; the raising PR's body carries the arithmetic.
 ['skills/objectstack-pm-dispatch/SKILL.md', 14391],
 ['skills/objectstack-query/SKILL.md', 5552], // -17 (was 5569)
 ['skills/objectstack-ui/SKILL.md', 25125], // -29 (was 25154)
 // 25125 -> 25143: the CRM UI Blueprint — the catalog's module-completeness
 // list, and the only place an agent is told what a finished module contains —
 // priced `src/views/**`, `src/apps/**`, dashboards and reports but never the
 // DATASET those last two bind, so an agent grew the app face and left the
 // analytics face silently empty (a module shipped with views, nav, approvals
 // and permissions was simply absent from the report builder). Maintainer
 // ruling 2026-08-31, director seat batch #15, verbatim and untranslated:
 // 「同意」 — accepting option C, whose text is: 「发布技能与文档的「长模块」路径
 // 必须把 dataset 声明列为模块完整性的一部分」. Arithmetic, in bytes because that
 // is what this convention divides: +204 for the new blueprint row, -7 for the
 // Reports row it lets shrink, and -77 for a sentence deleted in the same file
 // that restated report binding a second time inside its own paragraph — +120
 // net, 25113 -> 25143 tokens. The row's 12 tokens of headroom absorb part of
 // it, so the CEILING moves 18. The raising PR's body carries the same numbers.
 ['skills/objectstack-ui/SKILL.md', 25143],
 ['skills/objectstack-upgrade/SKILL.md', 8333], // -2 (was 8335)

 // ── the #12392 extension: the rest of the AUTHORED bundle ────────────────
Expand Down

5 changes: 3 additions & 2 deletions
skills/objectstack-ui/SKILL.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -688,7 +688,7 @@ allowed joins, intrinsic filter, dimensions, and certified measures. The legacy
per-widget inline query (`object` + `categoryField` + `valueField` + `aggregate`)
**was removed** — a widget now requires `dataset` + `values`; the closed schema
REJECTS the inline keys by name, and one lacking `dataset` fails `os validate`.
Reports bind the same way (`dataset` + `rows` + `values` + `runtimeFilter`). The dataset shape is
The dataset shape is
`DatasetSchema` — see `node_modules/@objectstack/spec/src/ui/dataset.zod.ts`.

A widget's presentation-scope `filter` flows into the query as the runtime
Expand DownExpand Up@@ -1404,8 +1404,9 @@ Use this CRM-style structure as the canonical UI assembly reference:
| Multi-view object UI | `src/views/*.view.ts` | Define default `list` + `form`, then named `listViews` / `formViews` for scenarios |
| **Public / anonymous form** | `src/views/*.view.ts` (formView with `sharing.allowAnonymous: true`) | Web-to-Lead / Web-to-Case. Auto-exposed at `GET/POST /api/v1/forms/:slug` |
| App navigation | `src/apps/*.app.ts` | Use grouped nav trees, `viewName` shortcuts, and `requiresObject` for capability-aware visibility |
| **Analytics dataset** | `src/datasets/*.dataset.ts` | One per object you want reportable — dashboards and reports bind a **declared** dataset by name, so an object without one has no analytics face |
| Dashboards | `src/dashboards/*.dashboard.ts` | Combine KPI + chart + table widgets with shared `dateRange` and `globalFilters` |
| Reports | `src/reports/*.report.ts` | Bind a `dataset` + `rows` (dimensions) + `values` (measures) for tabular/summary/matrix/joined analytics |
| Reports | `src/reports/*.report.ts` | Select `rows` (dimensions) + `values` (measures) from that dataset; tabular/summary/matrix/joined |
| Record pages | `src/pages/*.page.ts` | Compose `regions` + components (`page:header`, `record:highlights`, related lists, tabs) |
| User actions | `src/actions/*.actions.ts` | Use `flow` for orchestration and `modal` for parameterized bulk mutations |

Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Force GitHub README to respect dark mode
(function() {
var style = document.createElement('style');
style.textContent = '
.markdown-body {
color-scheme: dark light;
}
.markdown-body pre { background: #161b22 !important; }
.markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }
.markdown-body table th, .markdown-body table td { border-color: #30363d !important; }
.markdown-body img { background: #0d1117; }
.markdown-body blockquote { border-left-color: #8b949e; }
.markdown-body hr { border-color: #30363d; }
';
document.head.appendChild(style);
})();
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
docs(skills): make the analytics dataset a module-completeness line item by claude[bot] · Pull Request #13972 · objectstack-ai/objectstack · GitHub
Skip to content
docs(skills): make the analytics dataset a module-completeness line item#13972

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-zhuang
merged 1 commit into

from

Sep 1, 2026

+28

−5

 Merged


docs(skills): make the analytics dataset a module-completeness line item
#13972
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


12 changes: 10 additions & 2 deletions
content/docs/getting-started/build-with-claude-code.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -356,16 +356,24 @@ prompt you can give verbatim:
|:---|:---|:---|
| Data model — objects, fields, relationships, validations, seeds | `objectstack-data` | "Add an `account` object and link tickets to it with a required lookup. Seed three demo accounts." |
| Queries & reports over records | `objectstack-query` | "Show me the count of open tickets per priority, using an aggregation." |
| Views, dashboards, apps, record pages | `objectstack-ui` | "Add a dashboard with a metric for open tickets and a bar chart of tickets by priority." |
| Views, dashboards, apps, record pages | `objectstack-ui` | "Declare a `tickets` dataset over the ticket object, then add a dashboard with a metric for open tickets and a bar chart of tickets by priority." |
| Business automation — flows, approvals, schedules | `objectstack-automation` | "Every day at 9:00, escalate tickets that have been open more than 48 hours." |
| Permissions & row-level security | `objectstack-data` (security sections) | "Members should only see their own tickets; support managers see everything." |
| Formula / conditional-field logic (CEL) | `objectstack-formula` | "Make `resolved_at` required and visible only when status is resolved." |
| AI agents & tools inside your app | `objectstack-ai` | "Add an AI skill that triages new tickets into a priority." |
| REST/auth surface tuning | `objectstack-api` | "Restrict the ticket API to read-only for non-members." |
| Translations | `objectstack-i18n` | "Add a zh-CN translation bundle for the ticket object and app navigation." |

Two habits keep this reliable as the app grows:
Three habits keep this reliable as the app grows:

- **A module is not finished until its analytics face exists.** Objects, views
 and a nav entry make an object usable; they do not make it *reportable*.
 Dashboards and reports bind a **declared dataset** by name
 (`src/datasets/*.dataset.ts`) — the layer that carries the governed joins,
 filters and measure definitions an object does not express — so an object with
 no dataset simply never appears in the report builder. Ask for the dataset in
 the same breath as the views, and `objectstack-ui`'s completeness blueprint
 lists it as its own line item.
- **The gate applies to every domain.** Flows, dashboards, permissions, and
 translations all go through the same `npm run validate` — the agent should run
 it after each change, exactly as `AGENTS.md` instructs.
Expand Down

16 changes: 15 additions & 1 deletion
scripts/check-skills-token-ratchet.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -272,7 +272,21 @@ export const CEILINGS = new Map([
 // minimal anchor form; the raising PR's body carries the arithmetic.
 ['skills/objectstack-pm-dispatch/SKILL.md', 14391],
 ['skills/objectstack-query/SKILL.md', 5552], // -17 (was 5569)
 ['skills/objectstack-ui/SKILL.md', 25125], // -29 (was 25154)
 // 25125 -> 25143: the CRM UI Blueprint — the catalog's module-completeness
 // list, and the only place an agent is told what a finished module contains —
 // priced `src/views/**`, `src/apps/**`, dashboards and reports but never the
 // DATASET those last two bind, so an agent grew the app face and left the
 // analytics face silently empty (a module shipped with views, nav, approvals
 // and permissions was simply absent from the report builder). Maintainer
 // ruling 2026-08-31, director seat batch #15, verbatim and untranslated:
 // 「同意」 — accepting option C, whose text is: 「发布技能与文档的「长模块」路径
 // 必须把 dataset 声明列为模块完整性的一部分」. Arithmetic, in bytes because that
 // is what this convention divides: +204 for the new blueprint row, -7 for the
 // Reports row it lets shrink, and -77 for a sentence deleted in the same file
 // that restated report binding a second time inside its own paragraph — +120
 // net, 25113 -> 25143 tokens. The row's 12 tokens of headroom absorb part of
 // it, so the CEILING moves 18. The raising PR's body carries the same numbers.
 ['skills/objectstack-ui/SKILL.md', 25143],
 ['skills/objectstack-upgrade/SKILL.md', 8333], // -2 (was 8335)

 // ── the #12392 extension: the rest of the AUTHORED bundle ────────────────
Expand Down

5 changes: 3 additions & 2 deletions
skills/objectstack-ui/SKILL.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -688,7 +688,7 @@ allowed joins, intrinsic filter, dimensions, and certified measures. The legacy
per-widget inline query (`object` + `categoryField` + `valueField` + `aggregate`)
**was removed** — a widget now requires `dataset` + `values`; the closed schema
REJECTS the inline keys by name, and one lacking `dataset` fails `os validate`.
Reports bind the same way (`dataset` + `rows` + `values` + `runtimeFilter`). The dataset shape is
The dataset shape is
`DatasetSchema` — see `node_modules/@objectstack/spec/src/ui/dataset.zod.ts`.

A widget's presentation-scope `filter` flows into the query as the runtime
Expand DownExpand Up@@ -1404,8 +1404,9 @@ Use this CRM-style structure as the canonical UI assembly reference:
| Multi-view object UI | `src/views/*.view.ts` | Define default `list` + `form`, then named `listViews` / `formViews` for scenarios |
| **Public / anonymous form** | `src/views/*.view.ts` (formView with `sharing.allowAnonymous: true`) | Web-to-Lead / Web-to-Case. Auto-exposed at `GET/POST /api/v1/forms/:slug` |
| App navigation | `src/apps/*.app.ts` | Use grouped nav trees, `viewName` shortcuts, and `requiresObject` for capability-aware visibility |
| **Analytics dataset** | `src/datasets/*.dataset.ts` | One per object you want reportable — dashboards and reports bind a **declared** dataset by name, so an object without one has no analytics face |
| Dashboards | `src/dashboards/*.dashboard.ts` | Combine KPI + chart + table widgets with shared `dateRange` and `globalFilters` |
| Reports | `src/reports/*.report.ts` | Bind a `dataset` + `rows` (dimensions) + `values` (measures) for tabular/summary/matrix/joined analytics |
| Reports | `src/reports/*.report.ts` | Select `rows` (dimensions) + `values` (measures) from that dataset; tabular/summary/matrix/joined |
| Record pages | `src/pages/*.page.ts` | Compose `regions` + components (`page:header`, `record:highlights`, related lists, tabs) |
| User actions | `src/actions/*.actions.ts` | Use `flow` for orchestration and `modal` for parameterized bulk mutations |

Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Highlight search terms from Google/DuckDuckGo/Bing referrer
(function() {
var ref = document.referrer;
var terms = [];
if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {
var url = new URL(ref);
var q = url.searchParams.get('q') || url.searchParams.get('p');
if (q) {
terms = q.split(/\s+/).filter(function(t) { return t.length > 2; });
}
}
if (terms.length === 0) return;
var style = document.createElement('style');
style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';
document.head.appendChild(style);
function highlight(node) {
if (node.nodeType === 3) { // text node
var text = node.textContent;
var found = false;
terms.forEach(function(term) {
var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi');
if (regex.test(text)) {
found = true;
var frag = document.createDocumentFragment();
var parts = text.split(regex);
parts.forEach(function(part, i) {
if (i % 2 === 0) {
frag.appendChild(document.createTextNode(part));
} else {
var span = document.createElement('span');
span.className = 'userscript-highlight';
span.textContent = part;
frag.appendChild(span);
}
});
node.parentNode.replaceChild(frag, node);
}
});
} else if (node.nodeType === 1 && node.childNodes) { // element
var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];
if (!skipTags.includes(node.tagName)) {
Array.from(node.childNodes).forEach(highlight);
}
}
}
highlight(document.body);
// Re-highlight on dynamic content
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1 || node.nodeType === 3) highlight(node);
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
docs(skills): make the analytics dataset a module-completeness line item by claude[bot] · Pull Request #13972 · objectstack-ai/objectstack · GitHub
Skip to content
docs(skills): make the analytics dataset a module-completeness line item#13972

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-zhuang
merged 1 commit into

from

Sep 1, 2026

+28

−5

 Merged


docs(skills): make the analytics dataset a module-completeness line item
#13972
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


12 changes: 10 additions & 2 deletions
content/docs/getting-started/build-with-claude-code.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -356,16 +356,24 @@ prompt you can give verbatim:
|:---|:---|:---|
| Data model — objects, fields, relationships, validations, seeds | `objectstack-data` | "Add an `account` object and link tickets to it with a required lookup. Seed three demo accounts." |
| Queries & reports over records | `objectstack-query` | "Show me the count of open tickets per priority, using an aggregation." |
| Views, dashboards, apps, record pages | `objectstack-ui` | "Add a dashboard with a metric for open tickets and a bar chart of tickets by priority." |
| Views, dashboards, apps, record pages | `objectstack-ui` | "Declare a `tickets` dataset over the ticket object, then add a dashboard with a metric for open tickets and a bar chart of tickets by priority." |
| Business automation — flows, approvals, schedules | `objectstack-automation` | "Every day at 9:00, escalate tickets that have been open more than 48 hours." |
| Permissions & row-level security | `objectstack-data` (security sections) | "Members should only see their own tickets; support managers see everything." |
| Formula / conditional-field logic (CEL) | `objectstack-formula` | "Make `resolved_at` required and visible only when status is resolved." |
| AI agents & tools inside your app | `objectstack-ai` | "Add an AI skill that triages new tickets into a priority." |
| REST/auth surface tuning | `objectstack-api` | "Restrict the ticket API to read-only for non-members." |
| Translations | `objectstack-i18n` | "Add a zh-CN translation bundle for the ticket object and app navigation." |

Two habits keep this reliable as the app grows:
Three habits keep this reliable as the app grows:

- **A module is not finished until its analytics face exists.** Objects, views
 and a nav entry make an object usable; they do not make it *reportable*.
 Dashboards and reports bind a **declared dataset** by name
 (`src/datasets/*.dataset.ts`) — the layer that carries the governed joins,
 filters and measure definitions an object does not express — so an object with
 no dataset simply never appears in the report builder. Ask for the dataset in
 the same breath as the views, and `objectstack-ui`'s completeness blueprint
 lists it as its own line item.
- **The gate applies to every domain.** Flows, dashboards, permissions, and
 translations all go through the same `npm run validate` — the agent should run
 it after each change, exactly as `AGENTS.md` instructs.
Expand Down

16 changes: 15 additions & 1 deletion
scripts/check-skills-token-ratchet.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -272,7 +272,21 @@ export const CEILINGS = new Map([
 // minimal anchor form; the raising PR's body carries the arithmetic.
 ['skills/objectstack-pm-dispatch/SKILL.md', 14391],
 ['skills/objectstack-query/SKILL.md', 5552], // -17 (was 5569)
 ['skills/objectstack-ui/SKILL.md', 25125], // -29 (was 25154)
 // 25125 -> 25143: the CRM UI Blueprint — the catalog's module-completeness
 // list, and the only place an agent is told what a finished module contains —
 // priced `src/views/**`, `src/apps/**`, dashboards and reports but never the
 // DATASET those last two bind, so an agent grew the app face and left the
 // analytics face silently empty (a module shipped with views, nav, approvals
 // and permissions was simply absent from the report builder). Maintainer
 // ruling 2026-08-31, director seat batch #15, verbatim and untranslated:
 // 「同意」 — accepting option C, whose text is: 「发布技能与文档的「长模块」路径
 // 必须把 dataset 声明列为模块完整性的一部分」. Arithmetic, in bytes because that
 // is what this convention divides: +204 for the new blueprint row, -7 for the
 // Reports row it lets shrink, and -77 for a sentence deleted in the same file
 // that restated report binding a second time inside its own paragraph — +120
 // net, 25113 -> 25143 tokens. The row's 12 tokens of headroom absorb part of
 // it, so the CEILING moves 18. The raising PR's body carries the same numbers.
 ['skills/objectstack-ui/SKILL.md', 25143],
 ['skills/objectstack-upgrade/SKILL.md', 8333], // -2 (was 8335)

 // ── the #12392 extension: the rest of the AUTHORED bundle ────────────────
Expand Down

5 changes: 3 additions & 2 deletions
skills/objectstack-ui/SKILL.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -688,7 +688,7 @@ allowed joins, intrinsic filter, dimensions, and certified measures. The legacy
per-widget inline query (`object` + `categoryField` + `valueField` + `aggregate`)
**was removed** — a widget now requires `dataset` + `values`; the closed schema
REJECTS the inline keys by name, and one lacking `dataset` fails `os validate`.
Reports bind the same way (`dataset` + `rows` + `values` + `runtimeFilter`). The dataset shape is
The dataset shape is
`DatasetSchema` — see `node_modules/@objectstack/spec/src/ui/dataset.zod.ts`.

A widget's presentation-scope `filter` flows into the query as the runtime
Expand DownExpand Up@@ -1404,8 +1404,9 @@ Use this CRM-style structure as the canonical UI assembly reference:
| Multi-view object UI | `src/views/*.view.ts` | Define default `list` + `form`, then named `listViews` / `formViews` for scenarios |
| **Public / anonymous form** | `src/views/*.view.ts` (formView with `sharing.allowAnonymous: true`) | Web-to-Lead / Web-to-Case. Auto-exposed at `GET/POST /api/v1/forms/:slug` |
| App navigation | `src/apps/*.app.ts` | Use grouped nav trees, `viewName` shortcuts, and `requiresObject` for capability-aware visibility |
| **Analytics dataset** | `src/datasets/*.dataset.ts` | One per object you want reportable — dashboards and reports bind a **declared** dataset by name, so an object without one has no analytics face |
| Dashboards | `src/dashboards/*.dashboard.ts` | Combine KPI + chart + table widgets with shared `dateRange` and `globalFilters` |
| Reports | `src/reports/*.report.ts` | Bind a `dataset` + `rows` (dimensions) + `values` (measures) for tabular/summary/matrix/joined analytics |
| Reports | `src/reports/*.report.ts` | Select `rows` (dimensions) + `values` (measures) from that dataset; tabular/summary/matrix/joined |
| Record pages | `src/pages/*.page.ts` | Compose `regions` + components (`page:header`, `record:highlights`, related lists, tabs) |
| User actions | `src/actions/*.actions.ts` | Use `flow` for orchestration and `modal` for parameterized bulk mutations |

Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Strip utm_, fbclid, gclid, etc. from all links on page
(function() {
var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',
'ref', 'ref_src', 'source', 'medium', 'campaign'];
function cleanUrl(url) {
try {
var u = new URL(url, window.location.origin);
var changed = false;
trackingParams.forEach(function(p) {
if (u.searchParams.has(p)) {
u.searchParams.delete(p);
changed = true;
}
});
return changed ? u.toString() : url;
} catch (e) {
return url;
}
}
function cleanLinks() {
document.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
cleanLinks();
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1) {
if (node.tagName === 'A') cleanLinks();
node.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '
docs(skills): make the analytics dataset a module-completeness line item by claude[bot] · Pull Request #13972 · objectstack-ai/objectstack · GitHub
Skip to content
docs(skills): make the analytics dataset a module-completeness line item#13972

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-zhuang
merged 1 commit into

from

Sep 1, 2026

+28

−5

 Merged


docs(skills): make the analytics dataset a module-completeness line item
#13972
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


12 changes: 10 additions & 2 deletions
content/docs/getting-started/build-with-claude-code.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -356,16 +356,24 @@ prompt you can give verbatim:
|:---|:---|:---|
| Data model — objects, fields, relationships, validations, seeds | `objectstack-data` | "Add an `account` object and link tickets to it with a required lookup. Seed three demo accounts." |
| Queries & reports over records | `objectstack-query` | "Show me the count of open tickets per priority, using an aggregation." |
| Views, dashboards, apps, record pages | `objectstack-ui` | "Add a dashboard with a metric for open tickets and a bar chart of tickets by priority." |
| Views, dashboards, apps, record pages | `objectstack-ui` | "Declare a `tickets` dataset over the ticket object, then add a dashboard with a metric for open tickets and a bar chart of tickets by priority." |
| Business automation — flows, approvals, schedules | `objectstack-automation` | "Every day at 9:00, escalate tickets that have been open more than 48 hours." |
| Permissions & row-level security | `objectstack-data` (security sections) | "Members should only see their own tickets; support managers see everything." |
| Formula / conditional-field logic (CEL) | `objectstack-formula` | "Make `resolved_at` required and visible only when status is resolved." |
| AI agents & tools inside your app | `objectstack-ai` | "Add an AI skill that triages new tickets into a priority." |
| REST/auth surface tuning | `objectstack-api` | "Restrict the ticket API to read-only for non-members." |
| Translations | `objectstack-i18n` | "Add a zh-CN translation bundle for the ticket object and app navigation." |

Two habits keep this reliable as the app grows:
Three habits keep this reliable as the app grows:

- **A module is not finished until its analytics face exists.** Objects, views
 and a nav entry make an object usable; they do not make it *reportable*.
 Dashboards and reports bind a **declared dataset** by name
 (`src/datasets/*.dataset.ts`) — the layer that carries the governed joins,
 filters and measure definitions an object does not express — so an object with
 no dataset simply never appears in the report builder. Ask for the dataset in
 the same breath as the views, and `objectstack-ui`'s completeness blueprint
 lists it as its own line item.
- **The gate applies to every domain.** Flows, dashboards, permissions, and
 translations all go through the same `npm run validate` — the agent should run
 it after each change, exactly as `AGENTS.md` instructs.
Expand Down

16 changes: 15 additions & 1 deletion
scripts/check-skills-token-ratchet.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -272,7 +272,21 @@ export const CEILINGS = new Map([
 // minimal anchor form; the raising PR's body carries the arithmetic.
 ['skills/objectstack-pm-dispatch/SKILL.md', 14391],
 ['skills/objectstack-query/SKILL.md', 5552], // -17 (was 5569)
 ['skills/objectstack-ui/SKILL.md', 25125], // -29 (was 25154)
 // 25125 -> 25143: the CRM UI Blueprint — the catalog's module-completeness
 // list, and the only place an agent is told what a finished module contains —
 // priced `src/views/**`, `src/apps/**`, dashboards and reports but never the
 // DATASET those last two bind, so an agent grew the app face and left the
 // analytics face silently empty (a module shipped with views, nav, approvals
 // and permissions was simply absent from the report builder). Maintainer
 // ruling 2026-08-31, director seat batch #15, verbatim and untranslated:
 // 「同意」 — accepting option C, whose text is: 「发布技能与文档的「长模块」路径
 // 必须把 dataset 声明列为模块完整性的一部分」. Arithmetic, in bytes because that
 // is what this convention divides: +204 for the new blueprint row, -7 for the
 // Reports row it lets shrink, and -77 for a sentence deleted in the same file
 // that restated report binding a second time inside its own paragraph — +120
 // net, 25113 -> 25143 tokens. The row's 12 tokens of headroom absorb part of
 // it, so the CEILING moves 18. The raising PR's body carries the same numbers.
 ['skills/objectstack-ui/SKILL.md', 25143],
 ['skills/objectstack-upgrade/SKILL.md', 8333], // -2 (was 8335)

 // ── the #12392 extension: the rest of the AUTHORED bundle ────────────────
Expand Down

5 changes: 3 additions & 2 deletions
skills/objectstack-ui/SKILL.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -688,7 +688,7 @@ allowed joins, intrinsic filter, dimensions, and certified measures. The legacy
per-widget inline query (`object` + `categoryField` + `valueField` + `aggregate`)
**was removed** — a widget now requires `dataset` + `values`; the closed schema
REJECTS the inline keys by name, and one lacking `dataset` fails `os validate`.
Reports bind the same way (`dataset` + `rows` + `values` + `runtimeFilter`). The dataset shape is
The dataset shape is
`DatasetSchema` — see `node_modules/@objectstack/spec/src/ui/dataset.zod.ts`.

A widget's presentation-scope `filter` flows into the query as the runtime
Expand DownExpand Up@@ -1404,8 +1404,9 @@ Use this CRM-style structure as the canonical UI assembly reference:
| Multi-view object UI | `src/views/*.view.ts` | Define default `list` + `form`, then named `listViews` / `formViews` for scenarios |
| **Public / anonymous form** | `src/views/*.view.ts` (formView with `sharing.allowAnonymous: true`) | Web-to-Lead / Web-to-Case. Auto-exposed at `GET/POST /api/v1/forms/:slug` |
| App navigation | `src/apps/*.app.ts` | Use grouped nav trees, `viewName` shortcuts, and `requiresObject` for capability-aware visibility |
| **Analytics dataset** | `src/datasets/*.dataset.ts` | One per object you want reportable — dashboards and reports bind a **declared** dataset by name, so an object without one has no analytics face |
| Dashboards | `src/dashboards/*.dashboard.ts` | Combine KPI + chart + table widgets with shared `dateRange` and `globalFilters` |
| Reports | `src/reports/*.report.ts` | Bind a `dataset` + `rows` (dimensions) + `values` (measures) for tabular/summary/matrix/joined analytics |
| Reports | `src/reports/*.report.ts` | Select `rows` (dimensions) + `values` (measures) from that dataset; tabular/summary/matrix/joined |
| Record pages | `src/pages/*.page.ts` | Compose `regions` + components (`page:header`, `record:highlights`, related lists, tabs) |
| User actions | `src/actions/*.actions.ts` | Use `flow` for orchestration and `modal` for parameterized bulk mutations |

Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Auto-enable theater mode on YouTube
(function() {
function tryTheater() {
var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]');
if (btn && !btn.classList.contains('activated')) {
btn.click();
}
}
// Try immediately
tryTheater();
// Try after navigation (SPA)
var lastUrl = location.href;
setInterval(function() {
if (location.href !== lastUrl) {
lastUrl = location.href;
setTimeout(tryTheater, 500);
}
}, 1000);
// Also try on player load
var observer = new MutationObserver(tryTheater);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
docs(skills): make the analytics dataset a module-completeness line item by claude[bot] · Pull Request #13972 · objectstack-ai/objectstack · GitHub
Skip to content
docs(skills): make the analytics dataset a module-completeness line item#13972

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-zhuang
merged 1 commit into

from

Sep 1, 2026

+28

−5

 Merged


docs(skills): make the analytics dataset a module-completeness line item
#13972
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


12 changes: 10 additions & 2 deletions
content/docs/getting-started/build-with-claude-code.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -356,16 +356,24 @@ prompt you can give verbatim:
|:---|:---|:---|
| Data model — objects, fields, relationships, validations, seeds | `objectstack-data` | "Add an `account` object and link tickets to it with a required lookup. Seed three demo accounts." |
| Queries & reports over records | `objectstack-query` | "Show me the count of open tickets per priority, using an aggregation." |
| Views, dashboards, apps, record pages | `objectstack-ui` | "Add a dashboard with a metric for open tickets and a bar chart of tickets by priority." |
| Views, dashboards, apps, record pages | `objectstack-ui` | "Declare a `tickets` dataset over the ticket object, then add a dashboard with a metric for open tickets and a bar chart of tickets by priority." |
| Business automation — flows, approvals, schedules | `objectstack-automation` | "Every day at 9:00, escalate tickets that have been open more than 48 hours." |
| Permissions & row-level security | `objectstack-data` (security sections) | "Members should only see their own tickets; support managers see everything." |
| Formula / conditional-field logic (CEL) | `objectstack-formula` | "Make `resolved_at` required and visible only when status is resolved." |
| AI agents & tools inside your app | `objectstack-ai` | "Add an AI skill that triages new tickets into a priority." |
| REST/auth surface tuning | `objectstack-api` | "Restrict the ticket API to read-only for non-members." |
| Translations | `objectstack-i18n` | "Add a zh-CN translation bundle for the ticket object and app navigation." |

Two habits keep this reliable as the app grows:
Three habits keep this reliable as the app grows:

- **A module is not finished until its analytics face exists.** Objects, views
 and a nav entry make an object usable; they do not make it *reportable*.
 Dashboards and reports bind a **declared dataset** by name
 (`src/datasets/*.dataset.ts`) — the layer that carries the governed joins,
 filters and measure definitions an object does not express — so an object with
 no dataset simply never appears in the report builder. Ask for the dataset in
 the same breath as the views, and `objectstack-ui`'s completeness blueprint
 lists it as its own line item.
- **The gate applies to every domain.** Flows, dashboards, permissions, and
 translations all go through the same `npm run validate` — the agent should run
 it after each change, exactly as `AGENTS.md` instructs.
Expand Down

16 changes: 15 additions & 1 deletion
scripts/check-skills-token-ratchet.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -272,7 +272,21 @@ export const CEILINGS = new Map([
 // minimal anchor form; the raising PR's body carries the arithmetic.
 ['skills/objectstack-pm-dispatch/SKILL.md', 14391],
 ['skills/objectstack-query/SKILL.md', 5552], // -17 (was 5569)
 ['skills/objectstack-ui/SKILL.md', 25125], // -29 (was 25154)
 // 25125 -> 25143: the CRM UI Blueprint — the catalog's module-completeness
 // list, and the only place an agent is told what a finished module contains —
 // priced `src/views/**`, `src/apps/**`, dashboards and reports but never the
 // DATASET those last two bind, so an agent grew the app face and left the
 // analytics face silently empty (a module shipped with views, nav, approvals
 // and permissions was simply absent from the report builder). Maintainer
 // ruling 2026-08-31, director seat batch #15, verbatim and untranslated:
 // 「同意」 — accepting option C, whose text is: 「发布技能与文档的「长模块」路径
 // 必须把 dataset 声明列为模块完整性的一部分」. Arithmetic, in bytes because that
 // is what this convention divides: +204 for the new blueprint row, -7 for the
 // Reports row it lets shrink, and -77 for a sentence deleted in the same file
 // that restated report binding a second time inside its own paragraph — +120
 // net, 25113 -> 25143 tokens. The row's 12 tokens of headroom absorb part of
 // it, so the CEILING moves 18. The raising PR's body carries the same numbers.
 ['skills/objectstack-ui/SKILL.md', 25143],
 ['skills/objectstack-upgrade/SKILL.md', 8333], // -2 (was 8335)

 // ── the #12392 extension: the rest of the AUTHORED bundle ────────────────
Expand Down

5 changes: 3 additions & 2 deletions
skills/objectstack-ui/SKILL.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -688,7 +688,7 @@ allowed joins, intrinsic filter, dimensions, and certified measures. The legacy
per-widget inline query (`object` + `categoryField` + `valueField` + `aggregate`)
**was removed** — a widget now requires `dataset` + `values`; the closed schema
REJECTS the inline keys by name, and one lacking `dataset` fails `os validate`.
Reports bind the same way (`dataset` + `rows` + `values` + `runtimeFilter`). The dataset shape is
The dataset shape is
`DatasetSchema` — see `node_modules/@objectstack/spec/src/ui/dataset.zod.ts`.

A widget's presentation-scope `filter` flows into the query as the runtime
Expand DownExpand Up@@ -1404,8 +1404,9 @@ Use this CRM-style structure as the canonical UI assembly reference:
| Multi-view object UI | `src/views/*.view.ts` | Define default `list` + `form`, then named `listViews` / `formViews` for scenarios |
| **Public / anonymous form** | `src/views/*.view.ts` (formView with `sharing.allowAnonymous: true`) | Web-to-Lead / Web-to-Case. Auto-exposed at `GET/POST /api/v1/forms/:slug` |
| App navigation | `src/apps/*.app.ts` | Use grouped nav trees, `viewName` shortcuts, and `requiresObject` for capability-aware visibility |
| **Analytics dataset** | `src/datasets/*.dataset.ts` | One per object you want reportable — dashboards and reports bind a **declared** dataset by name, so an object without one has no analytics face |
| Dashboards | `src/dashboards/*.dashboard.ts` | Combine KPI + chart + table widgets with shared `dateRange` and `globalFilters` |
| Reports | `src/reports/*.report.ts` | Bind a `dataset` + `rows` (dimensions) + `values` (measures) for tabular/summary/matrix/joined analytics |
| Reports | `src/reports/*.report.ts` | Select `rows` (dimensions) + `values` (measures) from that dataset; tabular/summary/matrix/joined |
| Record pages | `src/pages/*.page.ts` | Compose `regions` + components (`page:header`, `record:highlights`, related lists, tabs) |
| User actions | `src/actions/*.actions.ts` | Use `flow` for orchestration and `modal` for parameterized bulk mutations |

Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Remove or un-stick sticky/fixed headers that block content
(function() {
function unstick() {
document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) {
if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {
el.style.position = 'static';
el.style.top = 'auto';
el.style.zIndex = 'auto';
}
});
}
unstick();
var observer = new MutationObserver(unstick);
observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });
})();
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
docs(skills): make the analytics dataset a module-completeness line item by claude[bot] · Pull Request #13972 · objectstack-ai/objectstack · GitHub
Skip to content
docs(skills): make the analytics dataset a module-completeness line item#13972

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-zhuang
merged 1 commit into

from

Sep 1, 2026

+28

−5

 Merged


docs(skills): make the analytics dataset a module-completeness line item
#13972
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


12 changes: 10 additions & 2 deletions
content/docs/getting-started/build-with-claude-code.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -356,16 +356,24 @@ prompt you can give verbatim:
|:---|:---|:---|
| Data model — objects, fields, relationships, validations, seeds | `objectstack-data` | "Add an `account` object and link tickets to it with a required lookup. Seed three demo accounts." |
| Queries & reports over records | `objectstack-query` | "Show me the count of open tickets per priority, using an aggregation." |
| Views, dashboards, apps, record pages | `objectstack-ui` | "Add a dashboard with a metric for open tickets and a bar chart of tickets by priority." |
| Views, dashboards, apps, record pages | `objectstack-ui` | "Declare a `tickets` dataset over the ticket object, then add a dashboard with a metric for open tickets and a bar chart of tickets by priority." |
| Business automation — flows, approvals, schedules | `objectstack-automation` | "Every day at 9:00, escalate tickets that have been open more than 48 hours." |
| Permissions & row-level security | `objectstack-data` (security sections) | "Members should only see their own tickets; support managers see everything." |
| Formula / conditional-field logic (CEL) | `objectstack-formula` | "Make `resolved_at` required and visible only when status is resolved." |
| AI agents & tools inside your app | `objectstack-ai` | "Add an AI skill that triages new tickets into a priority." |
| REST/auth surface tuning | `objectstack-api` | "Restrict the ticket API to read-only for non-members." |
| Translations | `objectstack-i18n` | "Add a zh-CN translation bundle for the ticket object and app navigation." |

Two habits keep this reliable as the app grows:
Three habits keep this reliable as the app grows:

- **A module is not finished until its analytics face exists.** Objects, views
 and a nav entry make an object usable; they do not make it *reportable*.
 Dashboards and reports bind a **declared dataset** by name
 (`src/datasets/*.dataset.ts`) — the layer that carries the governed joins,
 filters and measure definitions an object does not express — so an object with
 no dataset simply never appears in the report builder. Ask for the dataset in
 the same breath as the views, and `objectstack-ui`'s completeness blueprint
 lists it as its own line item.
- **The gate applies to every domain.** Flows, dashboards, permissions, and
 translations all go through the same `npm run validate` — the agent should run
 it after each change, exactly as `AGENTS.md` instructs.
Expand Down

16 changes: 15 additions & 1 deletion
scripts/check-skills-token-ratchet.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -272,7 +272,21 @@ export const CEILINGS = new Map([
 // minimal anchor form; the raising PR's body carries the arithmetic.
 ['skills/objectstack-pm-dispatch/SKILL.md', 14391],
 ['skills/objectstack-query/SKILL.md', 5552], // -17 (was 5569)
 ['skills/objectstack-ui/SKILL.md', 25125], // -29 (was 25154)
 // 25125 -> 25143: the CRM UI Blueprint — the catalog's module-completeness
 // list, and the only place an agent is told what a finished module contains —
 // priced `src/views/**`, `src/apps/**`, dashboards and reports but never the
 // DATASET those last two bind, so an agent grew the app face and left the
 // analytics face silently empty (a module shipped with views, nav, approvals
 // and permissions was simply absent from the report builder). Maintainer
 // ruling 2026-08-31, director seat batch #15, verbatim and untranslated:
 // 「同意」 — accepting option C, whose text is: 「发布技能与文档的「长模块」路径
 // 必须把 dataset 声明列为模块完整性的一部分」. Arithmetic, in bytes because that
 // is what this convention divides: +204 for the new blueprint row, -7 for the
 // Reports row it lets shrink, and -77 for a sentence deleted in the same file
 // that restated report binding a second time inside its own paragraph — +120
 // net, 25113 -> 25143 tokens. The row's 12 tokens of headroom absorb part of
 // it, so the CEILING moves 18. The raising PR's body carries the same numbers.
 ['skills/objectstack-ui/SKILL.md', 25143],
 ['skills/objectstack-upgrade/SKILL.md', 8333], // -2 (was 8335)

 // ── the #12392 extension: the rest of the AUTHORED bundle ────────────────
Expand Down

5 changes: 3 additions & 2 deletions
skills/objectstack-ui/SKILL.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -688,7 +688,7 @@ allowed joins, intrinsic filter, dimensions, and certified measures. The legacy
per-widget inline query (`object` + `categoryField` + `valueField` + `aggregate`)
**was removed** — a widget now requires `dataset` + `values`; the closed schema
REJECTS the inline keys by name, and one lacking `dataset` fails `os validate`.
Reports bind the same way (`dataset` + `rows` + `values` + `runtimeFilter`). The dataset shape is
The dataset shape is
`DatasetSchema` — see `node_modules/@objectstack/spec/src/ui/dataset.zod.ts`.

A widget's presentation-scope `filter` flows into the query as the runtime
Expand DownExpand Up@@ -1404,8 +1404,9 @@ Use this CRM-style structure as the canonical UI assembly reference:
| Multi-view object UI | `src/views/*.view.ts` | Define default `list` + `form`, then named `listViews` / `formViews` for scenarios |
| **Public / anonymous form** | `src/views/*.view.ts` (formView with `sharing.allowAnonymous: true`) | Web-to-Lead / Web-to-Case. Auto-exposed at `GET/POST /api/v1/forms/:slug` |
| App navigation | `src/apps/*.app.ts` | Use grouped nav trees, `viewName` shortcuts, and `requiresObject` for capability-aware visibility |
| **Analytics dataset** | `src/datasets/*.dataset.ts` | One per object you want reportable — dashboards and reports bind a **declared** dataset by name, so an object without one has no analytics face |
| Dashboards | `src/dashboards/*.dashboard.ts` | Combine KPI + chart + table widgets with shared `dateRange` and `globalFilters` |
| Reports | `src/reports/*.report.ts` | Bind a `dataset` + `rows` (dimensions) + `values` (measures) for tabular/summary/matrix/joined analytics |
| Reports | `src/reports/*.report.ts` | Select `rows` (dimensions) + `values` (measures) from that dataset; tabular/summary/matrix/joined |
| Record pages | `src/pages/*.page.ts` | Compose `regions` + components (`page:header`, `record:highlights`, related lists, tabs) |
| User actions | `src/actions/*.actions.ts` | Use `flow` for orchestration and `modal` for parameterized bulk mutations |

Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Universal Dark Mode - works on any site
(function() {
var enabled = true;
function applyDarkMode() {
if (!enabled) return;
// Create style element if it doesn't exist
var style = document.getElementById('universal-dark-mode-style');
if (!style) {
style = document.createElement('style');
style.id = 'universal-dark-mode-style';
document.head.appendChild(style);
}
// Dark mode CSS - inverts colors but preserves images/video
style.textContent = '
/* Invert everything except media */
html {
filter: invert(1) hue-rotate(180deg) !important;
background: #1a1a2e !important;
}
/* Restore images, videos, iframes, canvas */
img, video, iframe, canvas, svg, picture, [style*="background-image"] {
filter: invert(1) hue-rotate(180deg) !important;
}
/* Preserve specific elements that should not be inverted */
.no-dark-mode, .no-dark-mode *,
[data-theme="light"], [data-theme="light"],
.ace_editor, .ace_editor *,
.CodeMirror, .CodeMirror *,
.monaco-editor, .monaco-editor *,
.markdown-body pre, .markdown-body pre *,
.highlight, .highlight *,
pre code, pre code * {
filter: none !important;
}
/* Fix common UI elements */
.modal, .popup, .dropdown-menu, .tooltip, .popover {
filter: invert(1) hue-rotate(180deg) !important;
background: #2d2d44 !important;
border-color: #444 !important;
}
/* Scrollbars */
::-webkit-scrollbar { background: #1a1a2e !important; }
::-webkit-scrollbar-thumb { background: #444 !important; }
::-webkit-scrollbar-thumb:hover { background: #555 !important; }
/* Selection */
::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
';
}
function removeDarkMode() {
var style = document.getElementById('universal-dark-mode-style');
if (style) style.remove();
}
// Toggle with Alt+Shift+D
document.addEventListener('keydown', function(e) {
if (e.altKey && e.shiftKey && e.key === 'D') {
e.preventDefault();
enabled = !enabled;
if (enabled) {
applyDarkMode();
console.log('[Universal Dark Mode] Enabled');
} else {
removeDarkMode();
console.log('[Universal Dark Mode] Disabled');
}
}
});
// Apply on load
applyDarkMode();
// Re-apply on dynamic content
var observer = new MutationObserver(function(mutations) {
if (enabled && !document.getElementById('universal-dark-mode-style')) {
applyDarkMode();
}
});
observer.observe(document.head, { childList: true });
console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');
})();
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();
docs(skills): make the analytics dataset a module-completeness line item by claude[bot] · Pull Request #13972 · objectstack-ai/objectstack · GitHub
Skip to content
docs(skills): make the analytics dataset a module-completeness line item#13972

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

os-zhuang
merged 1 commit into

from

Sep 1, 2026

+28

−5

 Merged


docs(skills): make the analytics dataset a module-completeness line item
#13972
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


12 changes: 10 additions & 2 deletions
content/docs/getting-started/build-with-claude-code.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -356,16 +356,24 @@ prompt you can give verbatim:
|:---|:---|:---|
| Data model — objects, fields, relationships, validations, seeds | `objectstack-data` | "Add an `account` object and link tickets to it with a required lookup. Seed three demo accounts." |
| Queries & reports over records | `objectstack-query` | "Show me the count of open tickets per priority, using an aggregation." |
| Views, dashboards, apps, record pages | `objectstack-ui` | "Add a dashboard with a metric for open tickets and a bar chart of tickets by priority." |
| Views, dashboards, apps, record pages | `objectstack-ui` | "Declare a `tickets` dataset over the ticket object, then add a dashboard with a metric for open tickets and a bar chart of tickets by priority." |
| Business automation — flows, approvals, schedules | `objectstack-automation` | "Every day at 9:00, escalate tickets that have been open more than 48 hours." |
| Permissions & row-level security | `objectstack-data` (security sections) | "Members should only see their own tickets; support managers see everything." |
| Formula / conditional-field logic (CEL) | `objectstack-formula` | "Make `resolved_at` required and visible only when status is resolved." |
| AI agents & tools inside your app | `objectstack-ai` | "Add an AI skill that triages new tickets into a priority." |
| REST/auth surface tuning | `objectstack-api` | "Restrict the ticket API to read-only for non-members." |
| Translations | `objectstack-i18n` | "Add a zh-CN translation bundle for the ticket object and app navigation." |

Two habits keep this reliable as the app grows:
Three habits keep this reliable as the app grows:

- **A module is not finished until its analytics face exists.** Objects, views
 and a nav entry make an object usable; they do not make it *reportable*.
 Dashboards and reports bind a **declared dataset** by name
 (`src/datasets/*.dataset.ts`) — the layer that carries the governed joins,
 filters and measure definitions an object does not express — so an object with
 no dataset simply never appears in the report builder. Ask for the dataset in
 the same breath as the views, and `objectstack-ui`'s completeness blueprint
 lists it as its own line item.
- **The gate applies to every domain.** Flows, dashboards, permissions, and
 translations all go through the same `npm run validate` — the agent should run
 it after each change, exactly as `AGENTS.md` instructs.
Expand Down

16 changes: 15 additions & 1 deletion
scripts/check-skills-token-ratchet.mjs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -272,7 +272,21 @@ export const CEILINGS = new Map([
 // minimal anchor form; the raising PR's body carries the arithmetic.
 ['skills/objectstack-pm-dispatch/SKILL.md', 14391],
 ['skills/objectstack-query/SKILL.md', 5552], // -17 (was 5569)
 ['skills/objectstack-ui/SKILL.md', 25125], // -29 (was 25154)
 // 25125 -> 25143: the CRM UI Blueprint — the catalog's module-completeness
 // list, and the only place an agent is told what a finished module contains —
 // priced `src/views/**`, `src/apps/**`, dashboards and reports but never the
 // DATASET those last two bind, so an agent grew the app face and left the
 // analytics face silently empty (a module shipped with views, nav, approvals
 // and permissions was simply absent from the report builder). Maintainer
 // ruling 2026-08-31, director seat batch #15, verbatim and untranslated:
 // 「同意」 — accepting option C, whose text is: 「发布技能与文档的「长模块」路径
 // 必须把 dataset 声明列为模块完整性的一部分」. Arithmetic, in bytes because that
 // is what this convention divides: +204 for the new blueprint row, -7 for the
 // Reports row it lets shrink, and -77 for a sentence deleted in the same file
 // that restated report binding a second time inside its own paragraph — +120
 // net, 25113 -> 25143 tokens. The row's 12 tokens of headroom absorb part of
 // it, so the CEILING moves 18. The raising PR's body carries the same numbers.
 ['skills/objectstack-ui/SKILL.md', 25143],
 ['skills/objectstack-upgrade/SKILL.md', 8333], // -2 (was 8335)

 // ── the #12392 extension: the rest of the AUTHORED bundle ────────────────
Expand Down

5 changes: 3 additions & 2 deletions
skills/objectstack-ui/SKILL.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -688,7 +688,7 @@ allowed joins, intrinsic filter, dimensions, and certified measures. The legacy
per-widget inline query (`object` + `categoryField` + `valueField` + `aggregate`)
**was removed** — a widget now requires `dataset` + `values`; the closed schema
REJECTS the inline keys by name, and one lacking `dataset` fails `os validate`.
Reports bind the same way (`dataset` + `rows` + `values` + `runtimeFilter`). The dataset shape is
The dataset shape is
`DatasetSchema` — see `node_modules/@objectstack/spec/src/ui/dataset.zod.ts`.

A widget's presentation-scope `filter` flows into the query as the runtime
Expand DownExpand Up@@ -1404,8 +1404,9 @@ Use this CRM-style structure as the canonical UI assembly reference:
| Multi-view object UI | `src/views/*.view.ts` | Define default `list` + `form`, then named `listViews` / `formViews` for scenarios |
| **Public / anonymous form** | `src/views/*.view.ts` (formView with `sharing.allowAnonymous: true`) | Web-to-Lead / Web-to-Case. Auto-exposed at `GET/POST /api/v1/forms/:slug` |
| App navigation | `src/apps/*.app.ts` | Use grouped nav trees, `viewName` shortcuts, and `requiresObject` for capability-aware visibility |
| **Analytics dataset** | `src/datasets/*.dataset.ts` | One per object you want reportable — dashboards and reports bind a **declared** dataset by name, so an object without one has no analytics face |
| Dashboards | `src/dashboards/*.dashboard.ts` | Combine KPI + chart + table widgets with shared `dateRange` and `globalFilters` |
| Reports | `src/reports/*.report.ts` | Bind a `dataset` + `rows` (dimensions) + `values` (measures) for tabular/summary/matrix/joined analytics |
| Reports | `src/reports/*.report.ts` | Select `rows` (dimensions) + `values` (measures) from that dataset; tabular/summary/matrix/joined |
| Record pages | `src/pages/*.page.ts` | Compose `regions` + components (`page:header`, `record:highlights`, related lists, tabs) |
| User actions | `src/actions/*.actions.ts` | Use `flow` for orchestration and `modal` for parameterized bulk mutations |

Expand Down
Loading