create-caspian-app 0.2.0-beta.72 → 0.2.0-beta.73
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/.github/copilot-instructions.md +12 -3
- package/dist/AGENTS.md +15 -84
- package/package.json +1 -1
|
@@ -3,6 +3,12 @@
|
|
|
3
3
|
- Read `AGENTS.md` before working in `main.py`, `src/lib/**`, `.venv/Lib/site-packages/casp/**`, `public/js/**`, `prisma/**`, or `node_modules/caspian-utils/dist/docs/**`.
|
|
4
4
|
- Keep repo-wide always-on Copilot guidance in this file. Use `.github/instructions/**/*.instructions.md` for narrower task-, file-, library-, or implementation-specific guidance when that extra context should not load on every request.
|
|
5
5
|
|
|
6
|
+
## Document Ownership
|
|
7
|
+
|
|
8
|
+
- This file owns repo-wide always-on rules for the workspace.
|
|
9
|
+
- `AGENTS.md` should focus on task routing, runtime cross-checking, and packaged-doc maintenance rather than repeating full rule blocks from this file.
|
|
10
|
+
- When packaged docs need to point AI from a feature guide to the controlling runtime file, prefer `node_modules/caspian-utils/dist/docs/core-runtime-map.md` instead of duplicating the full module map in multiple pages.
|
|
11
|
+
|
|
6
12
|
## Global Rules
|
|
7
13
|
|
|
8
14
|
- Use this decision order: `caspian.config.json` for optional feature enablement, app runtime and app-owned code for current project behavior, matching workspace instruction files under `.github/instructions/**/*.instructions.md` for task-specific implementation guidance, installed `casp` runtime for framework internals, and packaged markdown docs for Caspian feature discovery and task routing.
|
|
@@ -33,7 +39,8 @@
|
|
|
33
39
|
- When `caspian.config.json` has `tailwindcss: true`, treat Python `merge_classes(...)` plus browser `twMerge(...)` as the only Tailwind class-merging contract: `merge_classes(...)` emits frontend-ready `{twMerge(...)}` expressions, and authored PulsePoint attribute expressions or scripts may call global `twMerge(...)` directly.
|
|
34
40
|
- Treat Caspian component usage as HTML-first in the current runtime: import Python components with `<!-- @import ... -->` and render them as kebab-cased `x-*` tags such as `<x-button />` or `<x-command-dialog />`.
|
|
35
41
|
- For CRUD operations and any browser-initiated reads from the backend, use route or backend `@rpc()` actions on the server and `pp.rpc(...)` from PulsePoint code on the client unless the user explicitly asks for another integration pattern.
|
|
36
|
-
- For route creation, keep page markup in `src/app/**/index.html`. If a route is UI-only, `index.html` alone is sufficient. Add `src/app/**/index.py` only as a companion when the same route needs metadata, `page()`, `@rpc()` actions, auth checks, caching, redirects, or other server-side behavior. Do not place route HTML in `index.py`; use a lone `index.py` only for non-visual routes such as redirect-only or action-only handlers.
|
|
42
|
+
- For route creation, keep page markup in `src/app/**/index.html`. If a route is UI-only, `index.html` alone is sufficient. Add `src/app/**/index.py` only as a companion when the same route needs metadata, `page()`, `@rpc()` actions, auth checks, caching, redirects, or other server-side behavior. Keep shared section wrappers in `layout.html` and use `layout.py` only for shared synchronous props or metadata. Do not place route HTML in `index.py` or layout HTML in `layout.py`; use a lone `index.py` only for non-visual routes such as redirect-only or action-only handlers.
|
|
43
|
+
- When the user asks for a dashboard, admin area, account area, or any grouped child-route section, follow the same mental model as the Next.js App Router: create a parent folder with `layout.html`, add `layout.py` only when that section needs shared synchronous props or metadata, and place the child routes beneath it. Use a normal folder such as `dashboard/` when the segment should appear in the URL, and use `(group)/` only when it should not.
|
|
37
44
|
- When a single route needs to affect a wrapping layout, have `page()` return `(render_page(__file__, page_context), {"dashboard_body_class": ...})` and consume that value as `[[ layout.dashboard_body_class ]]` in `layout.html`. Use `layout.py` when the same prop should apply across a whole subtree.
|
|
38
45
|
- For file uploads and file-manager flows, keep browser interaction in route templates, keep upload and delete `@rpc()` actions in the owning `src/app/**/index.py`, keep shared storage and persistence helpers in `src/lib/**`, store metadata in Prisma, and store browser-accessible blobs under `public/uploads/**` when the files should be served directly.
|
|
39
46
|
- Local upload helpers should create `public/uploads` on demand when it does not exist yet; do not assume the folder is committed ahead of time.
|
|
@@ -45,7 +52,7 @@
|
|
|
45
52
|
- Dynamic route params currently reach `page()` as a single positional `dict`, with query params injected by name and `request` injected by keyword when declared.
|
|
46
53
|
- In `layout.py`, return a dict for standard `[[ layout.* ]]` props. Use `render_layout(__file__, {...})` only when that layout should consume direct local variables such as `[[ my_class ]]` instead of `[[ layout.my_class ]]`.
|
|
47
54
|
- Do not assume `StateManager` survives across requests unless `request.state.session` is explicitly bridged from `request.session`.
|
|
48
|
-
- Route, layout, and component HTML templates must keep
|
|
55
|
+
- Route, layout, and component HTML templates must keep exactly one authored top-level parent node so Caspian can inject `pp-component` after component expansion. In source, that parent may be a native HTML element or a single imported `x-*` component tag, but it must resolve to one final HTML root. Keep any owned PulsePoint script inside that same parent, and keep top-of-file `<!-- @import ... -->` directives above it.
|
|
49
56
|
|
|
50
57
|
## BrowserSync URL Source Of Truth
|
|
51
58
|
|
|
@@ -94,13 +101,15 @@
|
|
|
94
101
|
### `src/app/**/*.html`
|
|
95
102
|
|
|
96
103
|
- Keep route templates and layouts server-rendered first, with PulsePoint enhancement as the default interactive layer.
|
|
104
|
+
- Keep visible page and layout markup in `index.html` and `layout.html`. Treat `index.py` and `layout.py` as backend companions for metadata, `page()` or `layout()`, `@rpc()` actions, auth checks, caching, redirects, and other server-side preparation, not as places to author visible HTML.
|
|
97
105
|
- When a route renders UI, author that markup in the route's `index.html` even if the route also has an `index.py` companion.
|
|
98
106
|
- When route templates import reusable Python components, render them as kebab-cased `x-*` tags such as `<x-button />` after a top-level `<!-- @import Button from "..." -->` directive.
|
|
99
107
|
- For route-level reactivity, prefer PulsePoint state, effects, refs, and template directives together with `pp.rpc(...)` instead of manual DOM mutation or ad hoc browser fetch code.
|
|
100
108
|
- Preserve Caspian template syntax such as `[[...]]` in layouts and `pp-*` runtime attributes in rendered HTML.
|
|
101
109
|
- Do not author `pp-component="..."` manually in route or layout templates; the Python render pipeline injects it onto the single root element.
|
|
102
110
|
- Do not author `type="text/pp"` manually in route or layout templates either. Use plain `<script>` in source and let the render path rewrite it.
|
|
103
|
-
- Keep authored route and layout templates to one top-level
|
|
111
|
+
- Keep authored route and layout templates to exactly one top-level parent node, the same constraint used for component templates. In source, that parent may be a native HTML element or a single imported `x-*` component tag. If a script is needed, keep it inside that parent instead of as a sibling top-level node.
|
|
112
|
+
- For dashboard, admin, or grouped sections with multiple child routes, prefer folder-level `layout.html` wrappers in `src/app/**` instead of repeating the same shell in each child route.
|
|
104
113
|
- For upload managers and similar interactive lists, prefer `pp.state(...)` plus `pp-for` over manual DOM painting so rerenders keep the list stable.
|
|
105
114
|
- Do not assume React, Vue, JSX-first component syntax, HTMX, or another frontend runtime unless the user explicitly requests one.
|
|
106
115
|
|
package/dist/AGENTS.md
CHANGED
|
@@ -8,6 +8,12 @@ When you work here, use `caspian.config.json` and the code that actually runs as
|
|
|
8
8
|
|
|
9
9
|
Do not treat the existence of a packaged doc as proof that the feature is enabled in this project.
|
|
10
10
|
|
|
11
|
+
## Document Ownership
|
|
12
|
+
|
|
13
|
+
- Keep repo-wide always-on rules in `.github/copilot-instructions.md`.
|
|
14
|
+
- Keep this file focused on decision order, task routing, workspace-specific clarifications, and packaged-doc maintenance.
|
|
15
|
+
- Keep packaged docs under `node_modules/caspian-utils/dist/docs/` framework-oriented and use `core-runtime-map.md` when those docs need to point AI back to `main.py` or the installed `casp` runtime.
|
|
16
|
+
|
|
11
17
|
## Decision Order
|
|
12
18
|
|
|
13
19
|
Use this order depending on the question being answered:
|
|
@@ -50,53 +56,14 @@ Important rules:
|
|
|
50
56
|
- confirm the current `local`, `external`, `ui`, and `uiExternal` values in `./settings/bs-config.json` before suggesting a browser URL, route test URL, or BrowserSync UI URL
|
|
51
57
|
- when frontend console logs, network errors, or terminal output suggest the app is being tested through the wrong URL or proxy port, re-check `./settings/bs-config.json` before changing app code
|
|
52
58
|
|
|
53
|
-
## Workspace
|
|
59
|
+
## Workspace Clarifications
|
|
60
|
+
|
|
61
|
+
Use `.github/copilot-instructions.md` for the repo-wide implementation rules. This file keeps only the workspace-specific retrieval and maintenance notes that help AI decide where to look next.
|
|
54
62
|
|
|
55
63
|
- Local Caspian docs live under `node_modules/caspian-utils/dist/docs/`.
|
|
56
64
|
- Workspace file instructions live under `.github/instructions/**/*.instructions.md` when the repo needs task- or library-specific AI guidance that should not be always-on.
|
|
57
|
-
- `
|
|
58
|
-
-
|
|
59
|
-
- Effective request order is therefore: `SessionMiddleware -> CSRFMiddleware -> AuthMiddleware -> RPCMiddleware`.
|
|
60
|
-
- App-level auth policy lives in `src/lib/auth/auth_config.py`.
|
|
61
|
-
- `main.py` applies auth settings with `configure_auth(build_auth_settings())` and registers `GithubProvider()` plus `GoogleProvider()`.
|
|
62
|
-
- In the app-owned starter config used in this workspace, routes start public because `src/lib/auth/auth_config.py` sets `is_all_routes_private=False` by default.
|
|
63
|
-
- Choose route privacy mode in `src/lib/auth/auth_config.py` at app setup time: use `is_all_routes_private=True` when most routes should require auth, otherwise keep `is_all_routes_private=False` and list only the protected routes in `private_routes`.
|
|
64
|
-
- In all-private mode, treat `public_routes` as the exception list. The runtime defaults keep `/` public and keep `auth_routes=["/signin", "/signup"]` public.
|
|
65
|
-
- `token_auto_refresh` does not make routes private in the current app; it only affects sliding-session refresh if `auth.refresh_session()` is called.
|
|
66
|
-
- Prefer logout via auth-protected RPC from page-level or component-level UI: `pp.rpc("signout")` backed by `@rpc(require_auth=True)`. Use a dedicated signout route only for plain form POST or no-JavaScript edge cases.
|
|
67
|
-
- Use PulsePoint as the default reactive frontend layer for app UI.
|
|
68
|
-
- When `caspian.config.json` has `tailwindcss: true`, treat Python `merge_classes(...)` plus browser `twMerge(...)` as the only Tailwind class-merging contract. `merge_classes(...)` emits frontend-ready `{twMerge(...)}` expressions, and authored PulsePoint expressions and scripts may call global `twMerge(...)` directly.
|
|
69
|
-
- For CRUD operations and any browser-initiated reads from the backend, use server `@rpc()` actions and client `pp.rpc(...)` calls unless the user explicitly asks for another integration pattern.
|
|
70
|
-
- When a single route needs to affect a wrapping layout, have `page()` return `(render_page(__file__, page_context), {"dashboard_body_class": ...})` and consume that value as `[[ layout.dashboard_body_class ]]` in `layout.html`. Use `layout.py` when the same prop should apply across an entire subtree.
|
|
71
|
-
- Protect customized `src/lib/auth/auth_config.py` from framework updates by adding `./src/lib/auth/auth_config.py` to `excludeFiles` in `caspian.config.json`.
|
|
72
|
-
- This workspace already has an app-owned Python database layer in `src/lib/prisma/`.
|
|
73
|
-
- Do not assume `src/lib/mcp/**`, `settings/restart-mcp.ts`, or MCP-related scripts exist unless `caspian.config.json` confirms MCP is enabled and the update workflow has run.
|
|
74
|
-
- Treat `package.json` scripts as opt-in operational commands, not default validation steps for ordinary source edits.
|
|
75
|
-
- Reuse `src/lib/prisma/prisma`, `PrismaClient`, generated models, and helper types instead of creating a second Python database abstraction.
|
|
76
|
-
- Prisma schema source of truth is `prisma/schema.prisma`.
|
|
77
|
-
- The schema-change workflow is: `npx prisma migrate dev`; if seed flow or `prisma/seed.ts` is involved, run `npx prisma generate` and then `npx prisma db seed`; then run `npx ppy generate`.
|
|
78
|
-
- `npx ppy generate` owns `src/lib/prisma/__init__.py`, `src/lib/prisma/db.py`, `src/lib/prisma/models.py`, and `settings/prisma-schema.json`; do not hand-edit those generated files.
|
|
79
|
-
- `caspian.config.json` is the first config file to check for enabled workspace features. Read the actual values instead of inferring them from the docs.
|
|
80
|
-
- As the app grows, prefer `src/components/` for reusable rendered UI and `src/lib/` for reusable non-UI support code.
|
|
81
|
-
- PulsePoint runtime code is shipped in `public/js/pp-reactive-v2.js` and loaded from `public/js/main.js`.
|
|
82
|
-
- Treat imported Python components as HTML-first `x-*` tags in authored templates, such as `<x-button />` or `<x-command-dialog />`.
|
|
83
|
-
- `pp-component` is injected by the Python render pipeline onto page, layout, and component roots; authored route and component templates should not add it manually.
|
|
84
|
-
- `main.py` runs `transform_scripts(...)`, so authored body `<script>` tags are rewritten to `<script type="text/pp">` in rendered HTML; route, layout, and component templates should write plain `<script>` in source.
|
|
85
|
-
- Route and component HTML templates must keep exactly one top-level lowercase HTML element so Caspian can inject `pp-component`. Think React-style single parent wrapper: good `<div>...</div>` with any owned script inside that same root, bad sibling top-level tags such as `<div>...</div><script ...></script>`.
|
|
86
|
-
- File-manager flows in this repo should keep upload and delete `@rpc()` actions in the owning `src/app/**/index.py`, keep shared filesystem and Prisma helpers in `src/lib/**`, persist metadata in Prisma, and store browser-accessible blobs under `public/uploads/**` when they should be served directly.
|
|
87
|
-
- Local upload helpers should create `public/uploads` on demand if the directory does not exist yet.
|
|
88
|
-
- When `npm run dev` is intentionally running, let that long-running stack own generated outputs such as `public/css/styles.css`, `settings/component-map.json`, `settings/files-list.json`, `__pycache__/`, and `.pyc` files. Treat those as generated artifacts, not authored source.
|
|
89
|
-
- `settings/component-map.json` and `settings/files-list.json` are generated by `settings/component-map.ts` and `settings/files-list.ts` through the dev and build pipelines. Analyze them when needed, but do not hand-edit them.
|
|
90
|
-
- `settings/bs-config.ts` should keep the public-root-relative upload directory name `uploads` in `PUBLIC_IGNORE_DIRS` so runtime uploads under `public/uploads/**` do not trigger BrowserSync reloads during the local stack.
|
|
91
|
-
- In the current router inside `main.py`, path params are passed to `page()` as the first positional `dict` argument.
|
|
92
|
-
- Matching query params can still be injected by name, and `request` is injected by keyword when declared.
|
|
93
|
-
- The installed `casp.layout` runtime calls `layout()` synchronously. Keep async I/O in `page()` or `@rpc()`.
|
|
94
|
-
- In `layout.py`, return a dict for standard `[[ layout.* ]]` props. Use `render_layout(__file__, {...})` only when that layout should consume direct local variables such as `[[ my_class ]]` instead of `[[ layout.my_class ]]`.
|
|
95
|
-
- `StateManager` reads and writes `request.state.session`, but the current middleware stack in `main.py` does not mirror `request.session` into `request.state.session`.
|
|
96
|
-
- Do not assume `StateManager` persistence survives across requests until that bridge exists.
|
|
97
|
-
- Route HTML caching uses `caches/` and `caches/cache_manifest.json` through `casp.cache_handler`.
|
|
98
|
-
- The current app tree has root templates in `src/app/`, and route-specific `index.py` files belong only where routes need server-side logic, metadata, or non-visual handling such as uploads or redirects.
|
|
99
|
-
- For route creation, keep page markup in `src/app/**/index.html`. If a route is UI-only, stop there. Add `src/app/**/index.py` only as a companion when the same route needs metadata, `page()`, `@rpc()` actions, auth checks, caching, redirects, or other server-side behavior. Do not place route HTML in `index.py`; use a lone `index.py` only for non-visual routes such as redirect-only or action-only handlers.
|
|
65
|
+
- Use `node_modules/caspian-utils/dist/docs/core-runtime-map.md` when a behavior is controlled by `main.py` or `.venv/Lib/site-packages/casp/**` and the owning file is not obvious yet.
|
|
66
|
+
- Before updating docs, verify runtime-specific claims such as middleware order, route param injection, `layout()` sync behavior, and `StateManager` persistence against the current `main.py` and installed `casp` package rather than copying older notes.
|
|
100
67
|
|
|
101
68
|
## Task Routing
|
|
102
69
|
|
|
@@ -106,6 +73,7 @@ Use this map before making changes.
|
|
|
106
73
|
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
|
|
107
74
|
| Project layout and file placement | `node_modules/caspian-utils/dist/docs/index.md`, `node_modules/caspian-utils/dist/docs/project-structure.md` | current workspace tree |
|
|
108
75
|
| Feature availability and tooling switches | `caspian.config.json` | current workspace tree, `main.py`, `prisma/**`, `public/js/**` |
|
|
76
|
+
| Framework internals and core-file lookup | `node_modules/caspian-utils/dist/docs/core-runtime-map.md` | `main.py`, `.venv/Lib/site-packages/casp/**`, matching feature docs |
|
|
109
77
|
| Library-specific and task-specific rules | matching `.github/instructions/**/*.instructions.md` files | `caspian.config.json`, current workspace tree, owning app and lib files |
|
|
110
78
|
| MCP server layout and launch flow | `node_modules/caspian-utils/dist/docs/mcp.md` | `settings/restart-mcp.ts`, `package.json`, `src/lib/mcp/**` |
|
|
111
79
|
| Routing, layouts, metadata | `node_modules/caspian-utils/dist/docs/routing.md` | `main.py`, `.venv/Lib/site-packages/casp/layout.py` |
|
|
@@ -117,45 +85,6 @@ Use this map before making changes.
|
|
|
117
85
|
| Validation | `node_modules/caspian-utils/dist/docs/validation.md` | `.venv/Lib/site-packages/casp/validate.py` |
|
|
118
86
|
| Database and seed flow | `node_modules/caspian-utils/dist/docs/database.md` | `prisma/schema.prisma`, `prisma/seed.ts`, `src/lib/prisma/**` |
|
|
119
87
|
|
|
120
|
-
## Editing Rules
|
|
121
|
-
|
|
122
|
-
- Keep app-owned shared code in `src/lib/**`.
|
|
123
|
-
- Keep reusable application UI components in `src/components/**`.
|
|
124
|
-
- Keep route-specific logic in `src/app/**`.
|
|
125
|
-
- For route creation, keep page markup in `src/app/**/index.html`. If a route is UI-only, `index.html` alone is sufficient. Add `src/app/**/index.py` only as a companion when the same route needs metadata, `page()`, `@rpc()` actions, auth checks, caching, redirects, or other server-side behavior. Do not place route HTML in `index.py`; use a lone `index.py` only for non-visual routes such as redirect-only or action-only handlers.
|
|
126
|
-
- If a single route only needs to tweak a parent layout, return `(render_page(__file__, ...), {"dashboard_body_class": ...})` from `page()` instead of introducing one-off global state or moving route HTML into `index.py`.
|
|
127
|
-
- For file-manager work, keep route-owned upload and delete `@rpc()` actions in `src/app/**/index.py`, keep shared storage and Prisma helper logic in `src/lib/**`, keep uploaded public blobs under `public/uploads/**`, and create that directory on demand in the helper when it is missing.
|
|
128
|
-
- When deciding between `src/components/**` and `src/lib/**`, put reusable rendered UI in `src/components/**` and put services, validators, adapters, database helpers, and other non-UI support code in `src/lib/**`.
|
|
129
|
-
- Read `caspian.config.json` before deciding whether a Caspian feature should be used, documented, scaffolded, or avoided in the current workspace.
|
|
130
|
-
- Treat `caspian.config.json` as the single source of truth for optional features. Do not use feature-specific files, commands, or docs until the corresponding flag is enabled.
|
|
131
|
-
- If a feature flag is false and the user wants that feature, ask for confirmation first, then update `caspian.config.json` and run `npx casp update project` so framework-managed files align with the new feature set.
|
|
132
|
-
- Do not run `package.json` scripts unless the user explicitly asks for them, the task genuinely requires that exact script, or deployment preparation needs `npm run build`.
|
|
133
|
-
- Use `npm run build` for deployment prep or an explicit build request, not as the default validation step for routine route, feature, or documentation edits.
|
|
134
|
-
- Never treat `__pycache__/` directories or `.pyc` files as authored source. Do not edit them manually and do not leave them in the final diff if a tool run creates them.
|
|
135
|
-
- Never hand-edit `settings/component-map.json` or `settings/files-list.json`. Inspect them if needed, but let the framework regeneration flow update them.
|
|
136
|
-
- Treat `.venv/Lib/site-packages/casp/**` as framework internals unless the task is explicitly about Caspian core behavior or installed-runtime documentation.
|
|
137
|
-
- When a task involves Python-side database access, reuse `src/lib/prisma/**` instead of introducing a parallel helper, but do not hand-edit generated files in that directory.
|
|
138
|
-
- When `prisma/schema.prisma` changes, run `npx prisma migrate dev` first. If seed flow or `prisma/seed.ts` is involved, run `npx prisma generate` and then `npx prisma db seed`. After that, run `npx ppy generate` so the Python ORM layer and `settings/prisma-schema.json` stay aligned.
|
|
139
|
-
- Keep auth policy in `src/lib/auth/auth_config.py`.
|
|
140
|
-
- Keep auth bootstrap, middleware ordering, provider wiring, and router behavior in `main.py`.
|
|
141
|
-
- Treat the app-owned `src/lib/auth/auth_config.py` as the effective default when generating routes for this repo: it starts public-first with `is_all_routes_private=False` unless the app explicitly switches to all-private mode.
|
|
142
|
-
- Decide all-private versus mixed public/private routing in `src/lib/auth/auth_config.py` before creating many routes; use all-private mode only when public routes are the minority.
|
|
143
|
-
- Keep public exceptions in `public_routes`, keep explicit protected routes in `private_routes` when not using all-private mode, and leave default `auth_routes` alone unless the app explicitly needs custom auth endpoints.
|
|
144
|
-
- Do not treat `token_auto_refresh` as the switch for private routes.
|
|
145
|
-
- For logout flows, prefer `pp.rpc("signout")` plus `@rpc(require_auth=True)` in page or component UI. Only scaffold a signout route for no-JavaScript, form-post, or full-navigation edge cases.
|
|
146
|
-
- When MCP is enabled, keep the app-owned FastMCP server in `src/lib/mcp/mcp_server.py` and the default config in `src/lib/mcp/fastmcp.json`. If those paths move, update `settings/restart-mcp.ts` and the MCP docs together.
|
|
147
|
-
- Use PulsePoint as the default reactive frontend and browser-side UI layer unless the user explicitly wants another stack.
|
|
148
|
-
- When HTML templates import reusable Python components, render them as kebab-cased `x-*` tags after a top-level `<!-- @import ... -->` directive.
|
|
149
|
-
- For CRUD operations and any browser-initiated reads from the backend, use `@rpc()` plus `pp.rpc(...)` as the default contract instead of ad hoc fetch or parallel REST endpoints unless the user explicitly asks for them.
|
|
150
|
-
- Treat `pp-component` as a framework-owned attribute on authored templates. Document it, but do not manually add it in normal route or component HTML.
|
|
151
|
-
- Treat `type="text/pp"` on PulsePoint scripts as a render-time attribute too. In authored route, layout, and component HTML, write plain `<script>` and let Caspian rewrite it.
|
|
152
|
-
- Keep route and component HTML templates to a single top-level lowercase HTML element so the Python side can inject `pp-component` safely. Keep any owned PulsePoint script inside that same root instead of as a sibling top-level node.
|
|
153
|
-
- Keep repo-wide always-on Copilot guidance consolidated in `.github/copilot-instructions.md`.
|
|
154
|
-
- Use `.github/instructions/**/*.instructions.md` for narrower file-, task-, library-, or implementation-specific instructions, and keep those files tightly scoped instead of duplicating general repo rules.
|
|
155
|
-
- When writing docs about route behavior, describe the param passing and layout behavior implemented in the current runtime, not generic upstream assumptions.
|
|
156
|
-
- When a runtime change affects documentation, update the matching page in `node_modules/caspian-utils/dist/docs/`.
|
|
157
|
-
- When a repo-level rule changes, update this file too.
|
|
158
|
-
|
|
159
88
|
## Docs Maintenance Rules
|
|
160
89
|
|
|
161
90
|
- Treat `node_modules/caspian-utils/dist/docs/**` as packaged Caspian feature docs and AI routing docs, not as a snapshot of the current project.
|
|
@@ -165,6 +94,7 @@ Use this map before making changes.
|
|
|
165
94
|
- Do not record this project's current feature flags, script inventory, or temporary file tree status inside the packaged docs.
|
|
166
95
|
- Gate optional docs with `caspian.config.json`. Use phrasing such as `when caspian.config.json enables MCP` instead of `this workspace has mcp: false`.
|
|
167
96
|
- Use the packaged docs to make AI aware of what Caspian can do, when a doc applies, and which project files should be inspected next.
|
|
97
|
+
- Use `core-runtime-map.md` to map packaged docs back to `main.py` and installed `casp` modules instead of restating the full runtime file list in every page.
|
|
168
98
|
- When `caspian.config.json` has `tailwindcss: true`, document Tailwind class handling as the current contract: Python `merge_classes(...)` emits frontend `{twMerge(...)}` expressions and browser `twMerge(...)` resolves conflicts.
|
|
169
99
|
- Keep repo-specific clarifications in this file or `.github/copilot-instructions.md` rather than embedding them in the packaged docs unless the behavior is truly framework-wide.
|
|
170
100
|
- Keep `index.md` and cross-links aligned so AI can discover the right task doc quickly.
|
|
@@ -176,4 +106,5 @@ Before merging doc or runtime changes:
|
|
|
176
106
|
|
|
177
107
|
1. Compare the claim or behavior against `main.py`, `src/lib/**`, and `.venv/Lib/site-packages/casp/**`.
|
|
178
108
|
2. Update the matching packaged doc in `node_modules/caspian-utils/dist/docs/` if the running behavior changed.
|
|
179
|
-
3. Update
|
|
109
|
+
3. Update `.github/copilot-instructions.md` if the repo-wide implementation rules changed.
|
|
110
|
+
4. Update this file if the decision order, task routing, workspace clarifications, or packaged-doc maintenance rules changed.
|