framework-py 0.1.0.dev2__py3-none-any.whl → 0.1.0.dev4__py3-none-any.whl

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.
Files changed (46) hide show
  1. framework/__init__.py +5 -0
  2. framework/__main__.py +64 -5
  3. framework/_agents_md.py +210 -0
  4. framework/_assets/adopt/rules.json +161 -0
  5. framework/_assets/features/jupyter.json +39 -0
  6. framework/_assets/features/quarto.json +18 -0
  7. framework/_assets/features/quarto_manuscript.json +35 -0
  8. framework/_assets/features/quarto_slides.json +29 -0
  9. framework/_assets/features/renv.json +20 -0
  10. framework/_assets/features/targets.json +34 -0
  11. framework/_assets/features/uv.json +17 -0
  12. framework/_assets/schema/layer.v1.json +45 -7
  13. framework/_assets/schema/layers.v1.json +49 -7
  14. framework/_assets/schema/spec.v1.json +38 -7
  15. framework/_assets/sets/packages/tidyverse-analysis.json +42 -0
  16. framework/_assets/sets/skills/framework.json +25 -0
  17. framework/_assets/sets/skills/ggplot2.json +26 -0
  18. framework/_assets/workflows/jupyter.json +14 -0
  19. framework/_assets/workflows/quarto.json +14 -0
  20. framework/_assets/workflows/scripts.json +18 -0
  21. framework/_defaults_cache.py +47 -0
  22. framework/_pages.py +228 -0
  23. framework/_paths.py +19 -9
  24. framework/_private.py +69 -0
  25. framework/adopt.py +365 -0
  26. framework/ai.py +13 -20
  27. framework/cloud.py +139 -14
  28. framework/create.py +395 -18
  29. framework/features.py +195 -0
  30. framework/hooks.py +69 -7
  31. framework/notebooks.py +9 -1
  32. framework/outputs.py +6 -1
  33. framework/quarto.py +77 -25
  34. framework/scaffold.py +50 -3
  35. framework/spec/check.py +31 -7
  36. framework/spec/merge.py +1 -0
  37. framework/spec/resolve.py +80 -6
  38. framework/storage.py +96 -50
  39. framework/templates/defaults.yml +0 -1
  40. framework/templates/skills/framework-outputs/SKILL.md +5 -5
  41. framework/templates/skills/framework-sensitive-data/SKILL.md +3 -2
  42. {framework_py-0.1.0.dev2.dist-info → framework_py-0.1.0.dev4.dist-info}/METADATA +1 -1
  43. framework_py-0.1.0.dev4.dist-info/RECORD +84 -0
  44. framework_py-0.1.0.dev2.dist-info/RECORD +0 -64
  45. {framework_py-0.1.0.dev2.dist-info → framework_py-0.1.0.dev4.dist-info}/WHEEL +0 -0
  46. {framework_py-0.1.0.dev2.dist-info → framework_py-0.1.0.dev4.dist-info}/licenses/LICENSE +0 -0
framework/_paths.py CHANGED
@@ -41,15 +41,25 @@ def directory(config: dict[str, Any], key: str, default: str, root: Path | None
41
41
  return in_root(value if isinstance(value, str) and value else default, root)
42
42
 
43
43
 
44
- def output_directory(config: dict[str, Any], kind: str, public: bool) -> Path:
44
+ def output_directory(
45
+ config: dict[str, Any], kind: str, public: bool, root: Path | None = None
46
+ ) -> Path:
45
47
  """Where outputs of one kind (tables, figures, ...) go.
46
48
 
47
- Sensitive projects split outputs into public and private folders; other
48
- projects use one folder per kind. This follows R's ``save_*()`` functions.
49
+ A project with private and public output folders (sensitive data on, or
50
+ ``outputs_private_*`` or ``outputs_public_*`` directories) splits by
51
+ ``public``. Any other project has one folder per kind. This follows R's
52
+ ``save_*()`` functions.
49
53
  """
50
- if config.get("project_type") == "project_sensitive":
51
- key = f"outputs_{'public' if public else 'private'}_{kind}"
52
- else:
53
- key = f"outputs_{kind}"
54
- default = f"outputs/public/{kind}" if public else f"outputs/{kind}"
55
- return directory(config, key, default)
54
+ directories = config.get("directories")
55
+ directories = directories if isinstance(directories, dict) else {}
56
+ security = config.get("security")
57
+ split = (
58
+ (isinstance(security, dict) and security.get("sensitive") is True)
59
+ or f"outputs_private_{kind}" in directories
60
+ or f"outputs_public_{kind}" in directories
61
+ )
62
+ if not split:
63
+ return directory(config, f"outputs_{kind}", f"outputs/{kind}", root)
64
+ side = "public" if public else "private"
65
+ return directory(config, f"outputs_{side}_{kind}", f"outputs/{side}/{kind}", root)
framework/_private.py ADDED
@@ -0,0 +1,69 @@
1
+ """The check before an upload: a path with "private" in it needs confirmation.
2
+
3
+ Uploads are always the user's explicit choice, so the check never refuses
4
+ outright. Any source whose full path contains "private", in any letter case,
5
+ is listed with a warning. An interactive session asks before uploading. A
6
+ session with no terminal (scripts, CI, notebooks run by agents) raises an
7
+ error unless ``include_private=True`` is passed.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import sys
13
+ import warnings
14
+ from collections.abc import Iterable
15
+ from pathlib import Path
16
+
17
+ from framework.errors import FrameworkError
18
+
19
+ # macOS resolves /tmp, /var, and /etc to /private/..., which the user did not name
20
+ _SYSTEM_PREFIX = "/private/"
21
+
22
+
23
+ def is_private_path(path: Path) -> bool:
24
+ """Whether the full absolute path contains "private", ignoring the system prefix."""
25
+ full = path.expanduser().resolve().as_posix()
26
+ if full.startswith(_SYSTEM_PREFIX):
27
+ full = full[len(_SYSTEM_PREFIX) - 1 :]
28
+ return "private" in full.lower()
29
+
30
+
31
+ def include_private_arg(include_private: bool, allow_private: bool | None) -> bool:
32
+ """``include_private``, honoring the deprecated ``allow_private`` name."""
33
+ if allow_private is None:
34
+ return include_private
35
+ warnings.warn(
36
+ "allow_private is deprecated; use include_private instead.",
37
+ DeprecationWarning,
38
+ stacklevel=3,
39
+ )
40
+ return include_private or allow_private
41
+
42
+
43
+ def confirm_private_upload(paths: Iterable[Path], include_private: bool) -> None:
44
+ """Warn about private paths among ``paths`` and ask before uploading them.
45
+
46
+ Raises:
47
+ FrameworkError: When there is no terminal to ask on and ``include_private`` is
48
+ False, or when the user declines.
49
+ """
50
+ if include_private:
51
+ return
52
+ flagged = [p for p in paths if is_private_path(p)]
53
+ if not flagged:
54
+ return
55
+ shown = "".join(f"\n {p}" for p in flagged[:5])
56
+ if len(flagged) > 5:
57
+ shown += f"\n ... and {len(flagged) - 5} more"
58
+ print(
59
+ f"Warning: {len(flagged)} file(s) to upload have 'private' in their path:{shown}",
60
+ file=sys.stderr,
61
+ )
62
+ if not sys.stdin.isatty():
63
+ raise FrameworkError(
64
+ "Not uploading files with 'private' in their path without confirmation. "
65
+ "Review them, then pass include_private=True to upload them."
66
+ )
67
+ answer = input("Upload them anyway? [y/N] ").strip().lower()
68
+ if answer not in ("y", "yes"):
69
+ raise FrameworkError("Cancelled. Nothing was uploaded.")
framework/adopt.py ADDED
@@ -0,0 +1,365 @@
1
+ """Adopt an existing project folder, or import its layout as a structure.
2
+
3
+ ``adopt()`` scans the folder's subfolders, proposes a Framework directory key
4
+ for each, and after your review writes ``settings.yml`` and
5
+ ``.framework/spec.json`` for the folders that are already there. It moves and
6
+ creates nothing else. ``structure_import()`` sends the same layout to
7
+ Framework Cloud as a private structure.
8
+
9
+ The scanner looks at folder names only, never at files or their contents.
10
+ The mapping rules are shared with R and ``fw`` (``inst/adopt/rules.json`` in
11
+ the R package): the first rule whose path matches a folder wins, and
12
+ folders no rule matches become ``extra_directories``.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import json
18
+ import re
19
+ import sys
20
+ from collections.abc import Callable, Mapping
21
+ from dataclasses import dataclass, field
22
+ from functools import cache
23
+ from importlib import resources
24
+ from pathlib import Path
25
+ from typing import Any
26
+
27
+ from framework._log import inform, show_messages
28
+ from framework.errors import FrameworkError
29
+
30
+ _KEY = re.compile(r"^[a-z][a-z0-9_]*$")
31
+ EXTRA = "extra"
32
+
33
+
34
+ @dataclass
35
+ class AdoptPlan:
36
+ """The proposed layout: folder -> role, in byte order of path.
37
+
38
+ A role is a Framework directory key, ``"extra"`` for a folder of its own,
39
+ or None for a folder that is left out. ``private`` lists every scanned
40
+ folder whose path contains "private".
41
+ """
42
+
43
+ roles: dict[str, str | None] = field(default_factory=dict)
44
+ private: list[str] = field(default_factory=list)
45
+
46
+ @property
47
+ def directories(self) -> dict[str, str]:
48
+ return {role: path for path, role in self.roles.items() if role not in (None, EXTRA)}
49
+
50
+ @property
51
+ def extra_directories(self) -> dict[str, dict[str, str]]:
52
+ extra: dict[str, dict[str, str]] = {}
53
+ taken = set(self.directories)
54
+ for path, role in self.roles.items():
55
+ if role == EXTRA:
56
+ key = _extra_key(path, taken)
57
+ taken.add(key)
58
+ extra[key] = {"label": path.rsplit("/", 1)[-1], "path": path}
59
+ return extra
60
+
61
+
62
+ @cache
63
+ def adopt_rules() -> dict[str, Any]:
64
+ """The shared mapping rules, as synced from the R package."""
65
+ path = resources.files("framework").joinpath("_assets/adopt/rules.json")
66
+ rules: dict[str, Any] = json.loads(path.read_text(encoding="utf-8"))
67
+ return rules
68
+
69
+
70
+ def _kept(path: str, rules: Mapping[str, Any]) -> bool:
71
+ skip = {name.lower() for name in rules.get("skip") or []}
72
+ parts = path.split("/")
73
+ return len(parts) <= int(rules.get("max_depth") or 3) and not any(
74
+ part.startswith(".") or part.lower() in skip for part in parts
75
+ )
76
+
77
+
78
+ def scan_folders(root: Path, rules: Mapping[str, Any] | None = None) -> list[str]:
79
+ """Subfolders of ``root``, as relative POSIX paths in byte order.
80
+
81
+ Hidden folders, the rules' ``skip`` folders (version control,
82
+ environments, caches), and everything under them are left out, and so are
83
+ folders more than ``max_depth`` levels deep. Only folder names are read.
84
+ """
85
+ rules = rules or adopt_rules()
86
+ found: list[str] = []
87
+
88
+ def walk(folder: Path) -> None:
89
+ for entry in folder.iterdir():
90
+ if entry.is_dir() and not entry.is_symlink():
91
+ relative = entry.relative_to(root).as_posix()
92
+ if _kept(relative, rules):
93
+ found.append(relative)
94
+ walk(entry)
95
+
96
+ walk(root)
97
+ return sorted(found, key=lambda p: p.encode("utf-8"))
98
+
99
+
100
+ def adopt_plan(
101
+ folders: list[str], language: str = "python", rules: Mapping[str, Any] | None = None
102
+ ) -> AdoptPlan:
103
+ """Propose a role for each folder with the shared rules.
104
+
105
+ The algorithm is the one in the R package's ``inst/conformance/README.md``
106
+ (adopt/): rules apply in order, each giving its key to the first folder
107
+ that equals one of its patterns, ignoring case. Folders inside an
108
+ assigned folder are covered by it. Each other folder with no assigned
109
+ folder inside it gets a role of its own (``"extra"``), unless its parent
110
+ does too.
111
+ """
112
+ rules = rules or adopt_rules()
113
+ kept = sorted((f for f in folders if _kept(f, rules)), key=lambda p: p.encode("utf-8"))
114
+ by_lower: dict[str, str] = {}
115
+ for folder in kept:
116
+ by_lower.setdefault(folder.lower(), folder)
117
+ assigned: dict[str, str] = {}
118
+ for rule in rules.get("rules") or []:
119
+ if rule.get("languages") and language not in rule["languages"]:
120
+ continue
121
+ for pattern in rule.get("patterns") or []:
122
+ match = by_lower.get(pattern.lower())
123
+ if match is not None and match not in assigned:
124
+ assigned[match] = rule["key"]
125
+ break
126
+
127
+ def qualifies(folder: str) -> bool:
128
+ return (
129
+ folder not in assigned
130
+ and not any(_inside(folder, a) for a in assigned)
131
+ and not any(_inside(a, folder) for a in assigned)
132
+ )
133
+
134
+ plan = AdoptPlan(private=[f for f in kept if "private" in f.lower()])
135
+ for folder in kept:
136
+ if folder in assigned:
137
+ plan.roles[folder] = assigned[folder]
138
+ elif qualifies(folder):
139
+ parent = folder.rsplit("/", 1)[0] if "/" in folder else None
140
+ if parent is None or not (parent in kept and qualifies(parent)):
141
+ plan.roles[folder] = EXTRA
142
+ return plan
143
+
144
+
145
+ def _inside(path: str, folder: str) -> bool:
146
+ return path.startswith(f"{folder}/")
147
+
148
+
149
+ def _extra_key(path: str, taken: set[str]) -> str:
150
+ key = re.sub(r"[^a-z0-9]+", "_", path.lower()).strip("_") or "folder"
151
+ if not key[0].isalpha():
152
+ key = f"dir_{key}"
153
+ candidate, n = key, 2
154
+ while candidate in taken:
155
+ candidate, n = f"{key}_{n}", n + 1
156
+ return candidate
157
+
158
+
159
+ # Review --------------------------------------------------------------------------------
160
+
161
+
162
+ def _table(plan: AdoptPlan) -> str:
163
+ width = max((len(p) for p in plan.roles), default=0)
164
+ lines = []
165
+ for number, (path, role) in enumerate(plan.roles.items(), start=1):
166
+ shown = "left out" if role is None else ("a folder of its own" if role == EXTRA else role)
167
+ lines.append(f" {number:>2}. {path:<{width}} -> {shown}")
168
+ return "\n".join(lines)
169
+
170
+
171
+ def _review(plan: AdoptPlan, ask: Callable[[str], str], cancelled: str) -> AdoptPlan:
172
+ """Let the person accept the plan, change a folder's role, leave a folder out, or cancel."""
173
+ paths = list(plan.roles)
174
+ while True:
175
+ print("Proposed folders:\n" + _table(plan), file=sys.stderr)
176
+ answer = ask(
177
+ "Press Enter to accept, type a number to change that folder's role, "
178
+ "-number to leave it out, or q to cancel: "
179
+ ).strip()
180
+ if not answer:
181
+ return plan
182
+ if answer.lower() == "q":
183
+ raise FrameworkError(cancelled)
184
+ out = answer.startswith("-")
185
+ number = answer.lstrip("-")
186
+ if not number.isdigit() or not 1 <= int(number) <= len(paths):
187
+ print(f"Type a number from 1 to {len(paths)}.", file=sys.stderr)
188
+ continue
189
+ path = paths[int(number) - 1]
190
+ if out:
191
+ plan.roles[path] = None
192
+ continue
193
+ role = ask(f"Role for {path} (a directory key such as inputs_raw, or {EXTRA}): ").strip()
194
+ if role != EXTRA and not _KEY.match(role):
195
+ print(f"'{role}' isn't a directory key.", file=sys.stderr)
196
+ elif role != EXTRA and role in plan.directories and plan.directories[role] != path:
197
+ print(f"{plan.directories[role]} already has the role {role}.", file=sys.stderr)
198
+ else:
199
+ plan.roles[path] = role
200
+
201
+
202
+ def _yes_no(ask: Callable[[str], str], question: str) -> bool:
203
+ return ask(f"{question} [y/N] ").strip().lower() in ("y", "yes")
204
+
205
+
206
+ # Public API ----------------------------------------------------------------------------
207
+
208
+
209
+ def adopt(path: str | Path = ".", yes: bool = False) -> Path:
210
+ """Make an existing folder a Framework project, in place.
211
+
212
+ The folder's subfolders are scanned (names only, at most three levels) and
213
+ each gets a proposed role: a Framework directory key such as
214
+ ``inputs_raw``, a folder of its own (``extra_directories``), or none.
215
+ You review the proposal, then ``settings.yml`` and ``.framework/spec.json``
216
+ are written for the folders that are there. Nothing is moved, and nothing
217
+ else is created.
218
+
219
+ A folder path that contains "private" gets a warning that suggests the
220
+ Privacy Sensitive layout. The sensitive setting is turned on only when you
221
+ say yes in the review.
222
+
223
+ Args:
224
+ path: The project folder.
225
+ yes: Accept the proposal without asking, as a script must. The sensitive
226
+ setting stays off.
227
+
228
+ Returns:
229
+ The project folder.
230
+
231
+ Raises:
232
+ FrameworkError: When the folder doesn't exist or is already a Framework project,
233
+ or when the review needs a terminal and ``yes`` is False.
234
+ """
235
+ show_messages()
236
+ root = Path(path).expanduser().resolve()
237
+ if not root.is_dir():
238
+ raise FrameworkError(f"Not a folder: {root}")
239
+ existing = [
240
+ n for n in ("settings.yml", "config.yml", ".framework/spec.json") if (root / n).exists()
241
+ ]
242
+ if existing:
243
+ raise FrameworkError(
244
+ f"{root} is already a Framework project (it has {', '.join(existing)})."
245
+ )
246
+ if not yes and not sys.stdin.isatty():
247
+ raise FrameworkError("adopt() needs a terminal to review the folders. Pass yes=True.")
248
+
249
+ plan = adopt_plan(scan_folders(root))
250
+ sensitive = False
251
+ if not yes:
252
+ plan = _review(plan, input, "Cancelled. Nothing was written.")
253
+ if plan.private:
254
+ # The same wording as R's adopt()
255
+ for folder in plan.private:
256
+ print(
257
+ f"'{folder}' looks private. Keep it out of git and away from AI assistants.",
258
+ file=sys.stderr,
259
+ )
260
+ print(
261
+ "The Privacy Sensitive layout keeps private and public data in separate "
262
+ "folders and adds safeguards for AI assistants.",
263
+ file=sys.stderr,
264
+ )
265
+ if not yes:
266
+ sensitive = _yes_no(input, "Turn on the sensitive-data setting for this project?")
267
+
268
+ spec = adopt_spec(root.name, plan, sensitive)
269
+ from framework.create import _record, _write_settings
270
+
271
+ _write_settings(root, spec)
272
+ _record(root, spec)
273
+ inform(f"Adopted {root} as a Framework project")
274
+ if not yes:
275
+ _offer_cloud(root, spec, plan)
276
+ return root
277
+
278
+
279
+ def adopt_spec(name: str, plan: AdoptPlan, sensitive: bool = False) -> dict[str, Any]:
280
+ """The resolved spec for an adopted folder: bare, flat settings, no tools."""
281
+ from framework.spec.resolve import spec_resolve
282
+
283
+ layer = {
284
+ "type": "bare",
285
+ "language": "python",
286
+ "core_files": False,
287
+ "settings_layout": "flat",
288
+ "tools": {"quarto": False, "uv": False},
289
+ "directories": plan.directories,
290
+ "extra_directories": plan.extra_directories,
291
+ "security": {"sensitive": sensitive},
292
+ }
293
+ spec = spec_resolve([layer], name).spec
294
+ spec["source"] = {"origin": "python"}
295
+ return spec
296
+
297
+
298
+ def _offer_cloud(root: Path, spec: Mapping[str, Any], plan: AdoptPlan) -> None:
299
+ from framework.cloud import CloudError, cloud_server, cloud_token, host, register_project
300
+
301
+ try:
302
+ server = cloud_server().url
303
+ except CloudError:
304
+ return
305
+ if cloud_token(server) is None:
306
+ return
307
+ if _yes_no(input, f"Register this project on {host(server)}?"):
308
+ register_project(root, str(spec["name"]), "bare", spec)
309
+ if _yes_no(input, f"Save this folder layout as a structure on {host(server)}?"):
310
+ _send_structure(str(spec["name"]), plan)
311
+
312
+
313
+ def structure_import(
314
+ path: str | Path = ".", name: str | None = None, yes: bool = False
315
+ ) -> dict[str, Any]:
316
+ """Save an existing folder's layout as a private structure on Framework Cloud.
317
+
318
+ The folders are scanned and mapped as in ``adopt()``, and you review the
319
+ mapping the same way. Only the confirmed folder paths are sent: never file
320
+ names or contents.
321
+
322
+ Args:
323
+ path: The project folder.
324
+ name: The structure's name. Default: the folder's name.
325
+ yes: Send the proposed mapping without asking, as a script must.
326
+
327
+ Returns:
328
+ The new structure: ``key`` (``"<owner>/<key>"``), ``name``, and ``url``.
329
+
330
+ Raises:
331
+ CloudError: When you are not logged in, or the server rejects the layout or
332
+ doesn't support structures.
333
+ FrameworkError: When the review needs a terminal and ``yes`` is False, or when
334
+ you cancel it.
335
+ """
336
+ show_messages()
337
+ root = Path(path).expanduser().resolve()
338
+ if not root.is_dir():
339
+ raise FrameworkError(f"Not a folder: {root}")
340
+ if not yes and not sys.stdin.isatty():
341
+ raise FrameworkError(
342
+ "structure_import() needs a terminal to review the folders. Pass yes=True."
343
+ )
344
+ plan = adopt_plan(scan_folders(root))
345
+ if not yes:
346
+ plan = _review(plan, input, "Cancelled. Nothing was sent.")
347
+ return _send_structure(name or root.name, plan)
348
+
349
+
350
+ def _send_structure(name: str, plan: AdoptPlan) -> dict[str, Any]:
351
+ from framework.cloud import CloudError, _MissingEndpointError, _require_token, api, cloud_server
352
+
353
+ server = cloud_server().url
354
+ token = _require_token(server)
355
+ body: dict[str, Any] = {"name": name, "directories": plan.directories}
356
+ if plan.extra_directories:
357
+ body["extra_directories"] = plan.extra_directories
358
+ try:
359
+ created = api("/api/v2/structures", token, server, method="POST", body=body)
360
+ except _MissingEndpointError as error:
361
+ raise CloudError("This Framework Cloud server doesn't support structures yet.") from error
362
+ if not isinstance(created, dict):
363
+ raise CloudError("The server returned an unexpected structure.")
364
+ inform(f"[ok] Saved the structure {created.get('key')}: {created.get('url')}")
365
+ return created
framework/ai.py CHANGED
@@ -8,6 +8,7 @@ from importlib.resources.abc import Traversable
8
8
  from pathlib import Path
9
9
  from typing import Any
10
10
 
11
+ from framework._agents_md import agents_md
11
12
  from framework.spec.check import ASSISTANTS
12
13
 
13
14
  AGENTS_DEFAULT = ".agents/skills"
@@ -47,25 +48,15 @@ def restricted_paths(spec: dict[str, Any]) -> list[str]:
47
48
  return sorted(restricted)
48
49
 
49
50
 
50
- def agents_md_stub(spec: dict[str, Any]) -> str:
51
- lines = [
52
- f"# {spec['name']}",
53
- "",
54
- "This is a Framework project (Python). Framework skills for this project are "
55
- "installed for your AI assistant.",
56
- "",
57
- "Start every notebook and script with `import framework as fw` and `fw.scaffold()`. "
58
- "It loads the project's settings, environment, and functions.",
59
- ]
60
- if spec.get("security", {}).get("sensitive"):
61
- folders = ", ".join(f"`{path}`" for path in restricted_paths(spec))
62
- lines += [
63
- "",
64
- f"This project holds restricted data. Do not read or print files in {folders}. "
65
- "Work from the data dictionary and simulated data instead.",
66
- ]
67
- lines += ["", "## Project Notes", ""]
68
- return "\n".join(lines) + "\n"
51
+ def restricted_notice(spec: dict[str, Any]) -> str | None:
52
+ """The line naming the folders agents must stay out of, for sensitive projects."""
53
+ if not spec.get("security", {}).get("sensitive"):
54
+ return None
55
+ folders = ", ".join(f"`{path}`" for path in restricted_paths(spec))
56
+ return (
57
+ f"This project holds restricted data. Do not read or print files in {folders}. "
58
+ "Work from the data dictionary and simulated data instead."
59
+ )
69
60
 
70
61
 
71
62
  def pointer_stub(name: str) -> str:
@@ -96,7 +87,9 @@ def write_ai_files(root: Path, spec: dict[str, Any]) -> list[str]:
96
87
  files = spec.get("files") or {}
97
88
 
98
89
  if spec.get("ai", {}).get("agents_md") == "stub" and "AGENTS.md" not in files:
99
- _write(root, "AGENTS.md", agents_md_stub(spec))
90
+ # The full guide, as R writes it; its skills table points at the first skills folder
91
+ skills_dir = folders[0] if folders else ".agents/skills"
92
+ _write(root, "AGENTS.md", agents_md(spec, skills_dir, restricted_notice(spec)))
100
93
  written.append("AGENTS.md")
101
94
  for stub in stubs:
102
95
  _write(root, stub, "@AGENTS.md\n" if stub == "CLAUDE.md" else pointer_stub(spec["name"]))