docs: engineering docs v1

apps/engineering/app/(home)/page.tsx

@@ -1,16 +1,13 @@
-import Link from "next/link";
-
-export default function HomePage() {
+export default function Page() {
   return (
-    <main className="flex h-screen flex-col justify-center text-center">
-      <h1 className="mb-4 text-2xl font-bold">Unkey Engineering</h1>
-      <p className="text-fd-muted-foreground">
-        You can open{" "}
-        <Link href="/docs" className="text-fd-foreground font-semibold underline">
-          /docs
-        </Link>{" "}
-        and see the documentation.{" "}
-      </p>
-    </main>
+    <div className="min-h-screen   border  text-center -mt-16 pt-16 flex items-center w-screen justify-center ">
+      <div>
+        <h1 className="text-7xl md:text-8xl font-bold  leading-none  uppercase tracking-tight">
+          BUILD BETTER
+          <br /> APIS FASTER
+        </h1>
+        <p className="text-xl mt-8 font-light ">How we work</p>
+      </div>
+    </div>
   );
 }

apps/engineering/app/docs/layout.tsx

@@ -1,48 +1,11 @@
 import { source } from "@/app/source";
-import { RootToggle } from "fumadocs-ui/components/layout/root-toggle";
 import { DocsLayout } from "fumadocs-ui/layouts/docs";
-import { Code, Component, Handshake, Terminal } from "lucide-react";
 import type { ReactNode } from "react";
 import { baseOptions } from "../layout.config";
 
 export default function Layout({ children }: { children: ReactNode }) {
   return (
-    <DocsLayout
-      tree={source.pageTree}
-      {...baseOptions}
-      sidebar={{
-        banner: (
-          <RootToggle
-            options={[
-              {
-                title: "Contributing",
-                description: "Create your first PR",
-                url: "/docs/contributing",
-                icon: <Code className="size-4 text-blue-600 dark:text-blue-400" />,
-              },
-              {
-                title: "Company",
-                description: "How we work",
-                url: "/docs/company",
-                icon: <Handshake className="size-4 text-amber-600 dark:text-amber-400" />,
-              },
-              {
-                title: "API Design",
-                description: "Look and feel",
-                url: "/docs/api-design",
-                icon: <Terminal className="size-4 text-emerald-600 dark:text-emerald-400" />,
-              },
-              {
-                title: "Architecture",
-                description: "How does Unkey work",
-                url: "/docs/architecture",
-                icon: <Component className="size-4 text-purple-600 dark:text-purple-400" />,
-              },
-            ]}
-          />
-        ),
-      }}
-    >
+    <DocsLayout tree={source.pageTree} {...baseOptions}>
       {children}
     </DocsLayout>
   );

apps/engineering/app/layout.config.tsx

@@ -9,13 +9,18 @@ import type { HomeLayoutProps } from "fumadocs-ui/layouts/home";
  */
 export const baseOptions: HomeLayoutProps = {
   nav: {
-    title: "Unkey Engineering",
+    title: "Unkey",
   },
   githubUrl: "https://github.com/unkeyed/unkey",
   links: [
     {
-      text: "Documentation",
-      url: "/docs",
+      text: "Contributing",
+      url: "/docs/contributing",
+      active: "nested-url",
+    },
+    {
+      text: "Architecture",
+      url: "/docs/architecture",
       active: "nested-url",
     },
     {

apps/engineering/content/docs/api-design/meta.json

@@ -1,3 +1,7 @@
 {
+  "title": "API Design",
+  "description": "Intuitive and helpful",
+  "icon": "Terminal2",
+  "root": true,
   "pages": ["rpc", "errors"]
 }

apps/engineering/content/docs/contributing/index.mdx

@@ -0,0 +1,87 @@
+---
+title: Getting Started
+---
+import { Step, Steps } from 'fumadocs-ui/components/steps';
+
+### Prerequisites
+
+You need the following services to run Unkey:
+
+
+<Callout>
+  We're currently working on making this optional.
+</Callout>
+- [Clerk](https://clerk.com?ref=unkey): Authentication
+
+
+You also need the following tools installed.
+
+- [Node](https://nodejs.org)
+- [pnpm](https://pnpm.io/installation)
+- [Docker](https://www.docker.com/products/docker-desktop)
+
+### Developing Unkey
+<Steps>
+  <Step>
+    #### Repository
+    Clone the [repo](https://github.com/unkeyed/unkey)
+
+    ```bash
+    git clone https://github.com/unkeyed/unkey
+    ```
+
+
+  </Step>
+
+  <Step>
+   #### Install
+    ```bash
+    cd unkey
+    corepack enable
+    pnpm install
+    ```
+
+  </Step>
+
+  <Step>
+  #### Setup local development
+  Unkey provides a CLI to setup our local development environment. Run the following command in your terminal:
+
+  ```bash
+  pnpm local
+  ```
+  <Callout type="warn">
+    Docker must be running for us to spin up the databases and supporting services.
+  </Callout>
+
+  You will be prompted to enter the following values:
+
+  - `CLERK_SECRET_KEY`: Your Clerk secret key.
+  - `NEXT_PUBLIC_CLERK_PUBLIC_KEY`: Your Clerk public key.
+
+
+
+  We will create the required `.env` files depending on the selection you've made.
+
+  </Step>
+</Steps>
+
+### About pnpm local command
+
+If you have already set up Unkey locally once and wish to bypass the manual input questions the next time, you can do so by using flags with the pnpm local command.
+
+    ```bash
+    pnpm local [options]
+    ```
+
+List of available options:
+
+- `--service=<service>`: Specifies which part of the application to develop. The values are `dashboard`, `api`, or `www`
+
+- `--skip-env`: Skips the environment setup prompt if specified.
+
+Example:
+
+    ```bash
+    pnpm local --service=dashboard --skip-env
+    ```

apps/engineering/content/docs/contributing/meta.json

@@ -0,0 +1,7 @@
+{
+  "title": "Contributing",
+  "description": "oss/acc",
+  "icon": "GitPullRequest",
+  "root": true,
+  "pages": ["index", "sdk-development", "testing", "versions"]
+}

apps/engineering/content/docs/contributing/sdk-development.mdx

@@ -0,0 +1,45 @@
+---
+title: SDK development
+description: Information for Unkey SDK developers
+---
+
+# Telemetry
+
+Unkey collects anonymous telemetry data to help us understand usage of the framework. If you're authoring an SDK, you should record usage information and send it via `Upstash-Telemetry` headers.
+
+### Typescript libraries
+
+The Unkey Typescript library `@unkey/api` is already set up to collect telemetry data. If you're writing a new SDK for a framework that makes use of that library
+under the hood, you just need to enable the user to disable telemetry; otherwise, pass it in the constructor. You can see an example of this via the Next.js SDK
+[here](https://github.com/unkeyed/unkey/blob/main/packages/nextjs/src/index.ts#L99).
+
+### Telemetry request headers
+
+Unkey records telemetry data via three headers. You can see an example of how this is used in the Typescript SDK [here](https://github.com/unkeyed/unkey/blob/main/packages/api/src/client.ts#L138)
+
+<Card title="Unkey-Telemetry-SDK" type="string">
+Comma-separated list of strings recording SDKs. Can be multiple SDKs; for instance, the Next.js SDK will record both the Next.js SDK version and
+Typescript SDK version.
+</Card>
+
+<Card title="Unkey-Telemetry-Platform" type="string">
+Referring to the platform where the calling application is deployed.
+
+For example: `Vercel`, `Cloudflare`, `AWS`, `Deno`
+</Card>
+
+<Card title="Unkey-Telemetry-Runtime" type="string">
+Referring to the programming runtime.
+
+For example: `edge-light`, `node@18`, `[email protected]`
+</Card>
+
+
+```bash Sending Telemetry
+curl -XPOST 'https://api.unkey.dev/v1/keys.verifyKey' \
+  -H "Content-Type: application/json" \
+  -H "Unkey-Telemetry-SDK: @unkey/[email protected]" \
+  -H "Unkey-Telemetry-Platform: Vercel" \
+  -H "Unkey-Telemetry-Runtime: edge-light" \
+  -d '{ "key": "<...>" }'
+```

apps/engineering/content/docs/contributing/testing.mdx

@@ -0,0 +1,28 @@
+---
+title: Testing
+description: James loves writing tests
+---
+
+
+We use [vitest](https://vitest.dev/) for our unit and integration tests. You can run the tests with:
+
+```bash
+pnpm install
+pnpm test
+```
+
+## API Tests
+
+`/apps/api` is our core product and needs to be heavily tested. Unit tests are not enough so we also use integration tests:
+
+### `integration`
+
+Full end to end tests require a running API either locally or in a deployed environment.
+  ```bash
+  cd apps/api
+
+  UNKEY_BASE_URL=
+  UNKEY_ROOT_KEY=
+  pnpm test:integration
+  ```
+

apps/engineering/content/docs/contributing/versions.mdx

@@ -0,0 +1,43 @@
+---
+title: Versioning
+description: "How to release new versions of the repository."
+---
+import { Step, Steps } from 'fumadocs-ui/components/steps';
+
+
+# Repository Version
+
+The main version of the repository is only for the `agent`. Sdks and other libraries have their own independent versioning.
+
+## Releasing packages
+
+All of the npm packages are versioned via changesets. This allows us to have a dedicated version for the agent, while still allowing us to version each package independently.
+
+To release a new version of a package, you need to create a new changeset with your PR. This will trigger a GitHub action that will publish the new version of the package.
+
+<Steps>
+    <Step title="Create Changeset">
+    In your feature branch, create a new changeset with `pnpm changeset`
+    </Step>
+
+    <Step title="Create PR">
+        Commit the generated changeset alongside your changes.
+        Changesets will be generated in the `.changeset` folder in the repository root.
+    </Step>
+
+    <Step title="Create PR" >
+        Create a new PR into `main`.
+    </Step>
+
+    <Step title="Versions are bumped" icon="robot">
+        *This step happens automatically in the CI*
+
+        Once the PR is approved and merged, we create a new PR automatically in the CI, which consumes the changesets and bumps the versions accordingly.
+    </Step>
+     <Step title="Packages are released" icon="robot">
+        *This step happens automatically in the CI*
+
+        Merging the version-bump pr will release all the packages to npm if necessary.
+    </Step>
+
+</Steps>