0.3.0

CHANGELOG.md

···
+### 0.3.0
+
+- New package `@typelex/cli`
+- See new recommended workflow on https://typelex.org/#install
+
 ### 0.2.0
 
 - Add `@external` support

DOCS.md

···
 
 The `@external` decorator tells the emitter to skip JSON output for that namespace. This is useful when referencing definitions from other Lexicons that you don't want to re-emit.
 
-You could collect external stubs in one file and import them:
-
-```typescript
-import "@typelex/emitter";
-import "../atproto-stubs.tsp";
-
-namespace app.bsky.actor.profile {
-  model Main {
-    labels?: (com.atproto.label.defs.SelfLabels | unknown);
-  }
-}
-```
-
-Then in `atproto-stubs.tsp`:
-
-```typescript
-import "@typelex/emitter";
-
-@external
-namespace com.atproto.label.defs {
-  model SelfLabels { }
-}
-
-@external
-namespace com.atproto.repo.defs {
-  model StrongRef { }
-  @token model SomeToken { }  // Note: Tokens still need @token
-}
-// ... more stubs
-```
+Starting with 0.3.0, typelex will automatically generate a `typelex/externals.tsp` file based on the JSON files in your `lexicons/` folder, and enforce that it's imported into your `typelex/main.tsp` entry point. However, this will *not* include Lexicons from your app's namespace, but only external ones.
 
 You'll want to ensure the real JSON for external Lexicons is available before running codegen.
 

packages/cli/package.json

···
 {
   "name": "@typelex/cli",
-  "version": "0.2.15",
+  "version": "0.3.0",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
···
     "@typelex/emitter": "workspace:*"
   },
   "peerDependencies": {
-    "@typelex/emitter": "^0.2.0"
+    "@typelex/emitter": "^0.3.0"
   }
 }

packages/cli/src/commands/init.ts

···
 
   return new Promise((resolve) => {
     rl.question(
-      `Enter your app's root namespace (e.g. ${pc.cyan("com.example.*")}): `,
+      `Which Lexicons do you want to write in typelex (e.g. ${pc.cyan("com.example.*")})? `,
       (answer) => {
         rl.close();
         resolve(answer.trim());
···
     return initSetup();
   }
 
-  console.log(`Adding ${gradientText("typelex")}...\n`);
+  console.log(gradientText("Adding typelex...") + "\n");
 
   // Detect package manager
   let packageManager = "npm";
···
 
   // Inform about external lexicons
   console.log(
-    `\nLexicons other than ${pc.cyan(namespace)} will be considered external.`,
+    `\nLexicons for ${pc.cyan(namespace)} will now be managed by typelex.`,
   );
+  console.log(`You can begin writing them in ${pc.cyan("typelex/main.tsp")}.`);
   console.log(
-    `Put them into the ${pc.cyan(displayLexiconsPath)} folder as JSON.\n`,
+    `Any external lexicons should remain in ${pc.cyan(displayLexiconsPath)}.\n`,
   );
 
   // Create typelex directory
···
   console.log(`\n${pc.green("✓")} ${pc.bold("All set!")}`);
   console.log(`\n${pc.bold("Next steps:")}`);
   console.log(
-    `  ${pc.dim("1.")} Edit ${pc.cyan("typelex/main.tsp")} to define your lexicons`,
+    `  ${pc.dim("1.")} Edit ${pc.cyan("typelex/main.tsp")} to define the ${pc.cyan(namespace)} lexicons`,
   );
   console.log(
     `  ${pc.dim("2.")} Keep putting external lexicons into ${pc.cyan(displayLexiconsPath)}`,

packages/emitter/package.json

···
 {
   "name": "@typelex/emitter",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "TypeSpec emitter for ATProto Lexicon definitions",
   "main": "dist/index.js",
   "type": "module",

packages/website/src/layouts/BaseLayout.astro

···
 
     <slot />
 
+    <script>
+      // Smooth scroll to top when clicking logo
+      document.addEventListener('DOMContentLoaded', () => {
+        const logo = document.querySelector('.logo');
+        if (logo) {
+          logo.addEventListener('click', (e) => {
+            // Allow Ctrl/Cmd+click to open in new tab
+            if (e.ctrlKey || e.metaKey || e.shiftKey) {
+              return;
+            }
+            e.preventDefault();
+            window.scrollTo({ top: 0, behavior: 'smooth' });
+          });
+        }
+      });
+    </script>
+
     {transparentNav && (
       <script>
         const nav = document.querySelector('.top-nav');

packages/website/src/pages/index.astro

···
 						<div class="step-content">
 							<h3>Add typelex to your app</h3>
 							<figure class="install-box" set:html={await highlightCode('npx @typelex/cli init', 'bash')} />
-							<p class="step-description">This will add a few things to your <code>package.json</code>, and create a <code>typelex/</code> folder.</p>
+							<p class="step-description">This will add a few things to your <code>package.json</code> and create a <code>typelex/</code> folder.</p>
 						</div>
 					</div>
 
···
 						<div class="step-number">2</div>
 						<div class="step-content">
 							<h3>Write your lexicons in <code>typelex/main.tsp</code></h3>
-							<figure class="install-box install-box-with-link">
-								<a href={createPlaygroundUrl(`import "@typelex/emitter";
-import "./externals.tsp";
-
-namespace com.myapp.example.profile {
-  /** My profile. */
-  @rec("literal:self")
-  model Main {
-    /** Free-form profile description.*/
-    @maxGraphemes(256)
-    description?: string;
-  }
-}`)} target="_blank" rel="noopener noreferrer" class="install-playground-link" aria-label="Open in playground">
-									<svg width="14" height="14" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
-										<path d="M6.5 3.5C6.5 3.22386 6.72386 3 7 3H13C13.2761 3 13.5 3.22386 13.5 3.5V9.5C13.5 9.77614 13.2761 10 13 10C12.7239 10 12.5 9.77614 12.5 9.5V4.70711L6.85355 10.3536C6.65829 10.5488 6.34171 10.5488 6.14645 10.3536C5.95118 10.1583 5.95118 9.84171 6.14645 9.64645L11.7929 4H7C6.72386 4 6.5 3.77614 6.5 3.5Z" fill="currentColor"/>
-										<path d="M3 5.5C3 4.67157 3.67157 4 4.5 4H5C5.27614 4 5.5 4.22386 5.5 4.5C5.5 4.77614 5.27614 5 5 5H4.5C4.22386 5 4 5.22386 4 5.5V11.5C4 11.7761 4.22386 12 4.5 12H10.5C10.7761 12 11 11.7761 11 11.5V11C11 10.7239 11.2239 10.5 11.5 10.5C11.7761 10.5 12 10.7239 12 11V11.5C12 12.3284 11.3284 13 10.5 13H4.5C3.67157 13 3 12.3284 3 11.5V5.5Z" fill="currentColor"/>
-									</svg>
-								</a>
-								<div set:html={await highlightCode(`import "@typelex/emitter";
-import "./externals.tsp";
-
-namespace com.myapp.example.profile {
-  /** My profile. */
-  @rec("literal:self")
-  model Main {
-    /** Free-form profile description.*/
-    @maxGraphemes(256)
-    description?: string;
-  }
-}`, 'typespec')} />
-							</figure>
+							<figure class="install-box" set:html={await highlightCode(installCode, 'typespec')} />
+							<p class="step-description">Your app's lexicons go here. They may reference any external ones from <code>lexicons/</code>.</p>
 						</div>
-						<p class="step-description">Your app's lexicons go here. They may reference any external ones from <code>lexicons/</code>.
 					</div>
 
 					<div class="install-step">
···
 	.install-section {
 		margin: 0;
 		padding: 0;
+		scroll-margin-top: 5rem;
 	}
 
 	.install-section h2 {