@goplausible/algorand-mcp 3.0.7

package/dist/resources/knowledge/taxonomy/liquid-auth:ARCHITECTURE.md

@@ -0,0 +1,241 @@
+## Overview
+
+### Components
+- Nest.js (Microservices/REST API)
+- Redis (Events/WebSockets)
+- MongoDB (SessionStore/Users)
+
+This service uses [FIDO2 REST API]() endpoints for credential creation and assertions.
+
+## FIDO2 Endpoints
+
+Two main components, Assertion and Attestation. 
+The purposed liquid extension is used to sign the FIDO2 responses with a different key pair and allow remote authentication
+
+### Liquid FIDO2 Extension
+
+```typescript
+// Authenticator Create Response
+interface LiquidClientAttestationExtensionResults {
+  liquid: {
+    type: string; // Currently only "algorand" supported
+    address: string; // Wallet Address
+    signature: string; // Base64URL Encoded Signature
+    requestId?: string // Optional Request ID , authenticate a remote user simaltaneously
+    device?: string // Optional Device Name
+  }
+}
+// Authenticator Get Response
+interface LiquidClientAssertionExtensionResults {
+  liquid: {
+    requestId?: string; // Optional Request ID
+  }
+}
+
+// Selector Options
+interface LiquidExtensionOptions {
+  liquid: boolean;
+}
+```
+
+### POST /attestation/request
+
+Returns the credential creation options supported by the service. It accepts
+the standard PublicKeyCreateOptions as the `body`. The response can be passed 
+to an available authenticator which will generate the credentials.
+
+The request must enable the `liquid` extension in order to sign the response.
+
+#### BODY
+
+```json
+{
+  "username": "2SPDE6XLJNXFTOO7OIGNRNKSEDOHJWVD3HBSEAPHONZQ4IQEYOGYTP6LXA",
+  "displayName": "Liquid Auth User",
+  "authenticatorSelection": {
+    "userVerification": "required"
+  },
+  "extensions": {
+    "liquid": true
+  }
+}
+```
+
+#### Example CredentialCreateOptions Response
+```json
+{
+  "challenge": "35JYpoXGnM4s8IICakWSLllcXy3Z_lc3AaLSl872qXM",
+  "rp": {
+    "name": "Algorand Foundation FIDO2 Server",
+    "id": "catfish-pro-wolf.ngrok-free.app"
+  },
+  "user": {
+    "id": "2SPDE6XLJNXFTOO7OIGNRNKSEDOHJWVD3HBSEAPHONZQ4IQEYOGYTP6LXA",
+    "name": "2SPDE6XLJNXFTOO7OIGNRNKSEDOHJWVD3HBSEAPHONZQ4IQEYOGYTP6LXA",
+    "displayName": "2SPDE6XLJNXFTOO7OIGNRNKSEDOHJWVD3HBSEAPHONZQ4IQEYOGYTP6LXA"
+  },
+  "pubKeyCredParams": [
+    {
+      "type": "public-key",
+      "alg": -7
+    },
+    {
+      "type": "public-key",
+      "alg": -257
+    }
+  ],
+  "timeout": 1800000,
+  "attestation": "none",
+  "excludeCredentials": [],
+  "authenticatorSelection": {
+    "userVerification": "required"
+  },
+  "extensions": {
+    "liquid": true
+  }
+}
+```
+### POST /attestation/response
+
+Receives the PublicKeyCredential result from the authenticator and validates the credential signature.
+`body` uses base64URL encoding for keys.
+
+The authenticator must include the `liquid` extension in the response with the signature and address.
+This will associate the credential with the wallet address and the credential can be used for future assertions without the need for signing with the wallet keys
+
+#### BODY
+```json
+{
+  "id": "AYMPi2Rbhcnu2gSHOO1TNvzDJ38iU00rrlCqyH874XCIEoIotRc7eVRFpx0TvsQurg7BAnXy5KnWdKC8LeWs0k0",
+  "type": "public-key",
+  "rawId": "AYMPi2Rbhcnu2gSHOO1TNvzDJ38iU00rrlCqyH874XCIEoIotRc7eVRFpx0TvsQurg7BAnXy5KnWdKC8LeWs0k0",
+  "clientExtensionResults": {
+    "liquid": {
+      "type": "algorand",
+      "requestId": "019097ff-bb8c-7c42-9700-f11b9446fad7",
+      "address": "2SPDE6XLJNXFTOO7OIGNRNKSEDOHJWVD3HBSEAPHONZQ4IQEYOGYTP6LXA",
+      "signature": "QY31mdH8AwpJ9p4pCXBO2iA5WdU-BjG52xEtJNuSJNHJIaJ10uzqk3FdR0fvYVfb_rzXTuWn4k1PFFeg-vpEDw",
+      "device": "Pixel 8 Pro"
+    }
+  },
+  "response": {
+    "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiMzVKWXBvWEduTTRzOElJQ2FrV1NMbGxjWHkzWl9sYzNBYUxTbDg3MnFYTSIsIm9yaWdpbiI6ImFuZHJvaWQ6YXBrLWtleS1oYXNoOlI4eE83cmxRV2FXTDRCbEZ5Z3B0V1JiNXFjS1dkZmp6WklhU1JpdDlYVnciLCJhbmRyb2lkUGFja2FnZU5hbWUiOiJmb3VuZGF0aW9uLmFsZ29yYW5kLmRlbW8ifQ",
+    "attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YVjFlpPmT7RcYTDeFJdKhDtiKwzb05n-ojlcqqYw5SomXZBFAAAAAAAAAAAAAAAAAAAAAAAAAAAAQQGDD4tkW4XJ7toEhzjtUzb8wyd_IlNNK65Qqsh_O-FwiBKCKLUXO3lURacdE77ELq4OwQJ18uSp1nSgvC3lrNJNpQECAyYgASFYIB2dcp3wanhReRhgRIpJCUfRSwkCvyE9OdvEL_NlncSJIlggkSIz7h7O5nrAXGJrkCOmeolChSc09eHzniCFLFxaKH0"
+  },
+  "device": "Pixel 8 Pro"
+}
+```
+
+
+### POST /assertion/request/:credId
+
+Request a PublicKeyGetCredentialOptions from the service. This differs slightly from the FIDO2 API conformance in order to limit
+allowed credentials.
+
+#### BODY (Optional)
+```json
+{
+  "authenticatorSelection": {
+    "userVerification": "required"
+  },
+  "extensions": {
+    "liquid": true
+  }
+}
+```
+
+#### Example Response
+```json
+{
+  "challenge": "0TXu4G4iu3sbAQopheoPe_CpnLJOB-QlIUvwFBC317Q",
+  "allowCredentials": [
+    {
+      "id": "AYMPi2Rbhcnu2gSHOO1TNvzDJ38iU00rrlCqyH874XCIEoIotRc7eVRFpx0TvsQurg7BAnXy5KnWdKC8LeWs0k0",
+      "type": "public-key"
+    }
+  ],
+  "timeout": 1800000,
+  "userVerification": "required",
+  "rpId": "catfish-pro-wolf.ngrok-free.app",
+  "extensions": {
+    "liquid": true
+  }
+}
+```
+
+### POST /assertion/response
+
+Base64URL encoded response from the authenticator. 
+Optionally add a `requestId` to also authenticate a remote session
+
+#### BODY
+```json
+ {
+  "id": "AYMPi2Rbhcnu2gSHOO1TNvzDJ38iU00rrlCqyH874XCIEoIotRc7eVRFpx0TvsQurg7BAnXy5KnWdKC8LeWs0k0",
+  "type": "public-key",
+  "rawId": "AYMPi2Rbhcnu2gSHOO1TNvzDJ38iU00rrlCqyH874XCIEoIotRc7eVRFpx0TvsQurg7BAnXy5KnWdKC8LeWs0k0",
+  "clientExtensionResults": {
+    "liquid": {
+      "requestId": "019097ff-bb8d-75d8-b950-33de977c2d3f"
+    }
+  },
+  "response": {
+    "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiMFRYdTRHNGl1M3NiQVFvcGhlb1BlX0NwbkxKT0ItUWxJVXZ3RkJDMzE3USIsIm9yaWdpbiI6ImFuZHJvaWQ6YXBrLWtleS1oYXNoOlI4eE83cmxRV2FXTDRCbEZ5Z3B0V1JiNXFjS1dkZmp6WklhU1JpdDlYVnciLCJhbmRyb2lkUGFja2FnZU5hbWUiOiJmb3VuZGF0aW9uLmFsZ29yYW5kLmRlbW8ifQ",
+    "authenticatorData": "lpPmT7RcYTDeFJdKhDtiKwzb05n-ojlcqqYw5SomXZAFAAAAAQ",
+    "signature": "MEUCIQDcV2y6ub3Qh8pyTCCLdWKRH_cmR2xlFuNy1Fn1QsSUygIgTZh9b6mB77C-aQrBj7Evb8u3S4j3vjlnSPAKcR7Kld4"
+  }
+}
+```
+
+#### Example Response
+```json
+{
+  "id": "M6RT4iT5FkNDM2i57MXzBhLDt9zl2CrLt2p4Ar03t2Q",
+  "wallet": "2SPDE6XLJNXFTOO7OIGNRNKSEDOHJWVD3HBSEAPHONZQ4IQEYOGYTP6LXA",
+  "credentials": [
+    {
+      "device": "Pixel 8 Pro",
+      "publicKey": "pQECAyYgASFYIB2dcp3wanhReRhgRIpJCUfRSwkCvyE9OdvEL_NlncSJIlggkSIz7h7O5nrAXGJrkCOmeolChSc09eHzniCFLFxaKH0",
+      "credId": "AYMPi2Rbhcnu2gSHOO1TNvzDJ38iU00rrlCqyH874XCIEoIotRc7eVRFpx0TvsQurg7BAnXy5KnWdKC8LeWs0k0",
+      "prevCounter": 0
+    }
+  ]
+}
+```
+## Signaling Service
+
+The signaling service is used to establish a WebRTC connection between the wallet and the website.
+
+### Events
+
+#### microservice:auth
+
+Emits to the event bus when a client attests or asserts a credential with a requestId.
+
+#### wss:link
+
+Submit a request to link the current client to a remote wallet. 
+The server will acknowledge the request when the `microservice:auth` event is received.
+
+```typescript
+const response: LinkMessage = await client.link(requestId)
+```
+
+#### wss:offer-description | wss:answer-description
+
+Wait for the server to emit an offer or answer description to the client.
+
+```typescript
+const response: string = await client.signal('offer' | 'answer')
+```
+
+#### wss:offer-candidate | wss:answer-candidate
+
+Emits the offer or answer ICE Candidates to connected clients.
+
+```typescript
+client.peerClient.onicecandidate=(event)=>{
+  client.socket.emit('offer-candidate', event.candidate.toJSON())
+}
+
+```

package/dist/resources/knowledge/taxonomy/liquid-auth:README.md

@@ -0,0 +1,105 @@
+# Algorand Authentication Service
+
+- [Vision](VISION.md)
+- [Architecture Diagram](ARCHITECTURE.md)
+- [Sequence Diagram](SEQUENCE.md)
+- [Decisions](.decisions/README.md)
+
+# Overview
+
+This project holds the standard FIDO2 api endpoints and the Proof of Knowledge for Algorand specific private keys.
+The api is a stateful session-based architecture with endpoint guards.
+A user must prove ownership of a private key to associate PublicKeyCredentials
+
+## Getting started
+
+### Prerequisites
+- Node.js 18+
+- Docker
+
+#### Clone the project
+
+```bash
+git clone git@github.com:algorandfoundation/liquid-auth.git && cd liquid-auth
+```
+
+### NGROK
+
+**note on VPNs**: Ngrok will not work with VPNs, so to run locally the project, `disable` it or `configure` your VPN's split tunneling to allow ngrok traffic.
+
+Sign up for a free account at [ngrok](https://ngrok.com/) and follow the instructions to get your <NGROK_AUTH_TOKEN> and <NGROK_STATIC_DOMAIN>.
+
+#### With Docker
+Don't run the ngrok commands directly as expressed in the ngrok guide as it will create run-time port conflicts.
+
+#### Without Docker
+ngrok will ask you to add your auth token to your configuration file.
+
+``` bash
+ngrok config add-authtoken <NGROK_AUTH_TOKEN>
+```
+
+Will then ask you to deploy your static domain, make sure to change the port to **5173** like this:
+
+``` bash
+ngrok http --domain=<NGROK_STATIC_DOMAIN> 5173
+```
+
+#### Configure NGROK
+
+Add a `ngrok.yml` configuration to the root directory.
+
+##### Example Configuration
+```yaml
+version: 2
+authtoken: <NGROK_AUTH_TOKEN>
+tunnels:
+  website:
+    addr: liquid-auth:5173
+    proto: http
+    domain: <NGROK_STATIC_DOMAIN>
+
+```
+*Make sure to update the `authtoken` and `domain` in the `ngrok.yml` file with your ngrok details.*
+
+#### Update the Service's .env.docker file
+
+Update the [.env.docker](.env.docker) file with the following keys with the values from ngrok:
+
+```bash
+HOSTNAME=<NGROK_STATIC_DOMAIN>
+ORIGIN=https://<NGROK_STATIC_DOMAIN>
+```
+
+### Start services
+
+Run the following command to start the backend:
+
+```bash
+docker-compose up -d
+```
+
+Navigate to the ngrok URL in your browser to test the FIDO2 feature.
+
+
+## Using the app
+
+#### Install the [Android client](https://github.com/algorandfoundation/liquid-auth-android/releases) to your device.
+
+![Step-1.png](.docs%2FStep-1.png)
+
+
+### QR Connect
+
+Open the Connect Modal on the website and scan the QR code using the "Connect" button on the Android device.
+Follow the instructions on the Android device to register a credential.
+
+
+![Step-1-QRCode.png](.docs%2FStep-1-QRCode.png)
+
+
+### Peer to Peer
+
+Once the credential is registered, you can send messages over the peer connection.
+
+![Step-2.png](.docs%2FStep-2.png)

package/dist/resources/knowledge/taxonomy/liquid-auth:SEQUENCE.md

@@ -0,0 +1,41 @@
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant Website
+    participant Server
+    participant Wallet
+    Note over Website, Wallet: Link devices
+    Website->>Server: Subscribe to 'wss:link'
+    Website-->>Website: Display QR Connect Request ID
+    Wallet->>Website: Scan QR Code
+    Server-->>Wallet: Get Challenge/Options
+    Wallet->>Server: POST FIDO2 Credential + Liquid Auth Extension
+    Server-->>Server: Validate Signatures
+    Server-->>Website: HTTPOnly Session
+    Server->>Wallet: Ok Response + HTTPOnly Session
+    Server->>Website: Emit to `wss:link` client
+    Note over Website, Wallet: Signaling Channels
+    Website-->>Server: Subscribe to 'wss:offer-description'
+    Website-->>Server: Subscribe to 'wss:offer-candidate'
+    Wallet-->>Server: Subscribe to 'wss:answer-description'
+    Wallet-->>Server: Subscribe to 'wss:answer-candidate'
+
+    Note over Website, Wallet: Peer Offer
+    Wallet-->>Wallet: On answer-description, set Remote SDP
+    Wallet-->>Wallet: On answer-candidate, add ICE Candidate
+    Wallet-->>Wallet: Create Peer Offer & DataChannel
+    Wallet-->>Server: Emit `wss:offer-description`
+    Wallet-->>Server: Emit `wss:offer-candidate`
+
+    Note over Website, Wallet: Peer Answer
+    Website-->>Website: On offer-description, set Remote SDP and create Answer
+    Website-->>Website: On offer-candidate, add ICE Candidate
+    Website-->>Server: Emit `wss:answer-description`
+    Website-->>Server: Emit `wss:answer-candidate`
+
+    Note over Website, Wallet: Data Channel
+    Website-->>Wallet: On DataChannel, Emit Messages
+
+```

package/dist/resources/knowledge/taxonomy/liquid-auth:VISION.md

@@ -0,0 +1,13 @@
+# Overview
+
+The vision of this project is to attest to services based on Algorand specific private keys.
+It relates to [ARC-31](https://github.com/algorandfoundation/ARCs/pull/160) and poses the question:
+
+> Can we use FIDO2 to authenticate users to a blockchain?
+
+This repository will serve as a reference implementation on the necessary endpoints to be
+compliant with `WebAuthn` and `FIDO2`.
+
+## Decisions
+
+See all Decisions in [.decisions/README.md](.decisions/README.md)

package/dist/resources/knowledge/taxonomy/liquid-auth:decisions:1-Service-Authentication.md

@@ -0,0 +1,18 @@
+# Overview
+
+FIDO2 is a standard for authentication. This repository seeks to explore the concrete implementations for 
+WebAuthn(Browser) and FIDO2(Android).
+
+## Decisions
+
+- Reference Implementation: https://codelabs.developers.google.com/codelabs/fido2-for-android#0
+- Use `Nest.js` as a backend for team familiarity
+- Use https://developer.chrome.com/docs/devtools/webauthn/ for Browser testing
+- Use https://simplewebauthn.dev/ for primary server library
+- Use https://developers.google.com/android/reference/com/google/android/gms/fido/fido2/package-summary for primary Android Library
+
+## Implementation
+
+Service Authentication is done using `Nest.js` and `Express-Session`. This
+is a simple, unsecure way to authenticate users. It is not recommended for
+production user. Adds routes for FIDO2 registration and authentication.

package/dist/resources/knowledge/taxonomy/liquid-auth:decisions:2-Bidirectional-Communication.md

@@ -0,0 +1,42 @@
+# Overview
+
+Communicating across platforms
+
+## Decisions
+
+- Remove dependency on Wallet Connect
+- Attest the knowledge of a wallet private key (ARC-31-Discussion)
+- Guard credential creation
+
+## Implementation
+
+Sessions should be guarded by the "proof of knowledge" of a wallet's private key. Currently
+there is a heavy reliance on Wallet Connect for communicating with Wallets. 
+
+
+This implementation should replace Wallet Connect with the following sequence
+```mermaid
+sequenceDiagram
+    participant Website
+    participant Server
+    participant Wallet
+    Note over Website, Wallet: Link devices
+    Website->>Server: Subscribe to 'wss:link'
+    Website-->>Website: Display QR Connect Nonce
+    Wallet->>Website: Scan QR Code
+    Wallet->>Server: POST Nonce + Signature
+    Server-->>Server: Validate Signature
+    Server-->>Website: HTTPOnly Session
+    Server->>Wallet: Ok Response + HTTPOnly Session
+    Server->>Website: Emit to `wss:link` client
+    Website-->>Website: Continue FIDO2 Flow
+    Wallet-->>Wallet: Continue FIDO2 Flow
+    
+```
+
+Once the session is attested to by the wallet private key, we allow for credential creation.
+This limits the knowledge emitted by the wallet keys to only the `nonce` for connecting. The only time
+the private key of the wallet is required is when registering credentials on a new device. 
+
+*Note: This process may be deprecated in the future in favor of `passkeys` which also support FIDO2 credentials with an 
+additional hybrid cross-platform authenticator.

package/dist/resources/knowledge/taxonomy/liquid-auth:decisions:3-Peer-to-Peer-Signaling.md

@@ -0,0 +1,60 @@
+# Overview
+
+Communicating across platforms in a decentralized manner
+
+## Decisions
+
+- Limit dependency on WebSockets to signaling
+- Allow bidirectional communication between peers
+- Enforce locality of device?
+
+## Implementation
+
+A WebSocket Service should establish the SDP handshake and emit ICE candidates for WebRTC clients.
+
+This implementation should replace Wallet Connect with the following sequence
+```mermaid
+sequenceDiagram
+    participant Website
+    participant Server
+    participant Wallet
+    Note over Website, Wallet: Link devices
+    Website->>Server: GET Challenge Message
+    Server->>Website: Send Challenge Message
+    
+    Website-->>Website: Display QR Connect Nonce
+    Website->>Server: Subscribe to 'wss:link'
+    Wallet->>Website: Scan QR Code
+    Wallet->>Server: POST Nonce + Signature + Answer
+    Server-->>Server: Validate Signature
+    Server-->>Website: HTTPOnly Session
+    Server->>Wallet: Ok Response + HTTPOnly Session
+    Server->>Website: Emit to `wss:link` client
+    Note over Website, Wallet: Passkeys/FIDO2
+    Website-->>Website: Continue FIDO2 Flow
+    Wallet-->>Wallet: Continue FIDO2 Flow
+    Note over Website, Wallet: Signaling Peer Offer/Answer
+    Website-->>Server: Subscribe to 'wss:answer-${address}'
+    Wallet-->>Server: Subscribe to 'wss:offer-${address}'
+
+    Website-->>Website: Create Peer Offer & DataChannel
+    Website-->>Server: POST Offer
+    Server-->>Wallet: Emit Offer
+    
+    Wallet-->>Wallet: Create Peer Answer with Offer & DataChannel
+   
+    Wallet-->>Server: POST Answer
+    Server-->>Website: Emit Answer
+    Website-->>Website: Set Remote SDP
+    Website-->>Website: Discover ICE Candidates
+    Website->>Server: Emit candidates to `wss:offer-${address}`
+    Server->>Wallet: Emit candidates to `wss:offer-${address}`
+    Wallet-->>Wallet: Set Candidates
+    Wallet-->>Wallet: Discover ICE Candidates
+    Wallet->>Server: Emit candidates to `wss:answer-${address}`
+    Server->>Website: Emit to `wss:answer`
+    Website->>Website: Set Candidates
+    
+```
+
+*Note: This process may be deprecated in the future in favor of `libp2p` which allows for an agnostic discovery layer and also supports the WebRTC transport

package/dist/resources/knowledge/taxonomy/liquid-auth:decisions:4-Fido-Extension.md

@@ -0,0 +1,51 @@
+# Overview
+
+Deprecate ARC-31/Arbitrary Auth Message in favor of custom FIDO2 extension
+
+## Decisions
+
+- Remove connect module and endpoints
+- Use FIDO2 Attestation/Assertions for device linking
+
+## Implementation
+
+```mermaid
+sequenceDiagram
+    participant Website
+    participant Server
+    participant Wallet
+    Note over Website, Wallet: Link devices
+    Website->>Server: Subscribe to 'wss:link'
+    Website-->>Website: Display QR Connect Request ID
+    Wallet->>Website: Scan QR Code
+    Server-->>Wallet: Get Challenge/Options
+    Wallet->>Server: POST FIDO2 Credential + Liquid Auth Signature
+    Server-->>Server: Validate Signatures
+    Server-->>Website: HTTPOnly Session
+    Server->>Wallet: Ok Response + HTTPOnly Session
+    Server->>Website: Emit to `wss:link` client
+    Note over Website, Wallet: Signaling Channels
+    Website-->>Server: Subscribe to 'wss:offer-description'
+    Website-->>Server: Subscribe to 'wss:offer-candidate'
+    Wallet-->>Server: Subscribe to 'wss:answer-description'
+    Wallet-->>Server: Subscribe to 'wss:answer-candidate'
+    
+    Note over Website, Wallet: Peer Offer
+    Wallet-->>Wallet: On answer-description, set Remote SDP
+    Wallet-->>Wallet: On answer-candidate, add ICE Candidate
+    Wallet-->>Wallet: Create Peer Offer & DataChannel
+    Wallet-->>Server: Emit `wss:offer-description`
+    Wallet-->>Server: Emit `wss:offer-candidate`
+    
+    Note over Website, Wallet: Peer Answer
+    Website-->>Website: On offer-description, set Remote SDP and create Answer
+    Website-->>Website: On offer-candidate, add ICE Candidate
+    Website-->>Server: Emit `wss:answer-description`
+    Website-->>Server: Emit `wss:answer-candidate`
+    
+    Note over Website, Wallet: Data Channel
+    Website-->>Wallet: On DataChannel, Emit Messages
+    
+```
+
+*Note: It may be possible to handle signaling in a fully decentralized manner in the future. 

package/dist/resources/knowledge/taxonomy/liquid-auth:decisions:README.md

@@ -0,0 +1,6 @@
+# Decisions for this Project
+
+- [1. Service Authentication](1-Service-Authentication.md)
+- [2. Bidirectional-Communications](2-Bidirectional-Communication.md)
+- [3. Peer-to-Peer-Signaling](3-Peer-to-Peer-Signaling.md)
+- [4. Fido-Extension](4-Fido-Extension.md)

package/dist/resources/knowledge/taxonomy/liquid-auth:docs:README.md

@@ -0,0 +1,54 @@
+# Starlight Starter Kit: Basics
+
+[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)
+
+```
+npm create astro@latest -- --template starlight
+```
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics)
+[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/starlight/tree/main/examples/basics)
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fwithastro%2Fstarlight%2Ftree%2Fmain%2Fexamples%2Fbasics&project-name=my-starlight-docs&repository-name=my-starlight-docs)
+
+> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+
+## 🚀 Project Structure
+
+Inside of your Astro + Starlight project, you'll see the following folders and files:
+
+```
+.
+├── public/
+├── src/
+│   ├── assets/
+│   ├── content/
+│   │   ├── docs/
+│   │   └── config.ts
+│   └── env.d.ts
+├── astro.config.mjs
+├── package.json
+└── tsconfig.json
+```
+
+Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.
+
+Images can be added to `src/assets/` and embedded in Markdown with a relative link.
+
+Static assets, like favicons, can be placed in the `public/` directory.
+
+## 🧞 Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| Command                   | Action                                           |
+| :------------------------ | :----------------------------------------------- |
+| `npm install`             | Installs dependencies                            |
+| `npm run dev`             | Starts local dev server at `localhost:4321`      |
+| `npm run build`           | Build your production site to `./dist/`          |
+| `npm run preview`         | Preview your build locally, before deploying     |
+| `npm run astro ...`       | Run CLI commands like `astro add`, `astro check` |
+| `npm run astro -- --help` | Get help using the Astro CLI                     |
+
+## 👀 Want to learn more?
+
+Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).