diff --git a/.prettierignore b/.prettierignore
new file mode 100644
index 0000000..fa29cdf
--- /dev/null
+++ b/.prettierignore
@@ -0,0 +1 @@
+**
\ No newline at end of file
diff --git a/astro.config.mjs b/astro.config.mjs
index 80de9cb..af55412 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -20,16 +20,38 @@ export default defineConfig({
           icon: "github",
           label: "GitHub",
           href: "https://github.com/midnames/docs",
+        }, {
+          icon: "twitter",
+          label: "Twitter",
+          href: "https://x.com/midnames"
         },
+        {
+          icon: "linkedin",
+          label: "LinkedIn",
+          href: "https://www.linkedin.com/company/midnames/"
+        }
+
       ],
       sidebar: [
         {
           label: "Guides",
-          autogenerate: { directory: "guides" },
+          items: [
+            {label: "Quickstart", slug: "guides/quickstart"},
+            {label: "Buy Domains", slug: "guides/buy_domain"},
+            {label: "Transfer .night domains", slug: "guides/transfer_domain"},
+            {label: "Update domain fields", slug: "guides/update_fields"},
+            {label: "MNS domain specification", slug: "guides/valid_domains"}
+          ]
         },
         {
           label: "SDK Reference",
-          autogenerate: { directory: "reference" },
+          items: [
+            {label: "Domain Operations", slug: "reference/operations"},
+            {label: "Domain Resolution", slug: "reference/resolve"},
+            {label: "TypeScript Types", slug: "reference/types"},
+            {label: "Utility Functions", slug: "reference/utils"},
+            {label: "Profile Widget", slug: "reference/widget"}
+          ]
         },
       ],
       plugins: [
diff --git a/src/content/docs/guides/index.mdx b/src/content/docs/guides/index.mdx
index c84c3c5..e0a85fa 100644
--- a/src/content/docs/guides/index.mdx
+++ b/src/content/docs/guides/index.mdx
@@ -1,10 +1,54 @@
 ---
 title: Guides
-description: Here are some guides to help you get started with Midnames, the .night domain registry.
+description: Step-by-step guides for using Midnames and the .night domain registry
 sidebar:
   hidden: true
 ---
 
-Here are some guides to help you get started with Midnames, the .night domain registry.
+import { CardGrid, LinkCard } from "@astrojs/starlight/components";
 
-Look through the list on the left to find a guide that suits your needs.
+Step-by-step guides to help you get started with Midnames, the .night domain registry, and the Midnames SDK.
+
+## Getting Started
+
+<CardGrid>
+  <LinkCard
+    title="Quick Start"
+    description="Get up and running with the Midnames SDK in 5 minutes. Perfect for developers integrating name resolution."
+    href="/guides/quickstart/"
+  />
+  <LinkCard
+    title="Buy a .night domain"
+    description="Get your own .night domain to represent your identity on the Midnight Network."
+    href="/guides/buy_domain/"
+  />
+</CardGrid>
+
+## Managing Your Domain
+
+<CardGrid>
+  <LinkCard
+    title="Update domain fields"
+    description="Learn how to update profile information, social links, and custom metadata in your domain."
+    href="/guides/update_fields/"
+  />
+  <LinkCard
+    title="Transfer a .night domain"
+    description="Safely transfer your .night domain to another user on the Midnight Network."
+    href="/guides/transfer_domain/"
+  />
+</CardGrid>
+
+## Specifications
+
+<CardGrid>
+  <LinkCard
+    title="MNS Specification"
+    description="Understand the rules and specifications for valid .night domain names."
+    href="/guides/valid_domains/"
+  />
+</CardGrid>
+
+## SDK Documentation
+
+Looking for API documentation? Check out the [SDK Reference](/reference/) section for complete API docs, React components, utility functions, and TypeScript types.
diff --git a/src/content/docs/guides/quickstart.mdx b/src/content/docs/guides/quickstart.mdx
new file mode 100644
index 0000000..b951d9a
--- /dev/null
+++ b/src/content/docs/guides/quickstart.mdx
@@ -0,0 +1,405 @@
+---
+title: Quick Start
+description: Get started with the Midnames SDK in 5 minutes
+sidebar:
+  label: Quick Start
+  badge:
+    text: Start here
+    variant: success
+---
+
+import { Aside, Steps, Code } from "@astrojs/starlight/components";
+
+Get started with the Midnames SDK in minutes. This guide covers installation, basic usage, and common patterns for both DApp and wallet developers.
+
+## What is Midnames SDK?
+
+Midnames SDK is a TypeScript library for integrating the Midnight Name Service (MNS) into your applications. It allows you to:
+
+- **Resolve** `.night` domains to blockchain addresses
+- **Display** rich profile information with pre-built React components
+- **Manage** domain fields, ownership, and settings (with wallet integration)
+
+<Aside type="tip">
+  **Perfect for:** 
+  - DApp developers adding human-readable names 
+  - Wallet developers building name resolution features 
+  - Anyone building on the Midnight Network
+</Aside>
+
+## Installation
+
+<Steps>
+
+1. **Install the SDK**
+
+   ```bash
+   npm install @midnames/sdk
+   ```
+
+   For React components, also install peer dependencies:
+
+   ```bash
+   npm install react react-dom lucide-react
+   ```
+
+2. **Import and start using**
+
+   ```typescript
+   import { resolveDomain } from "@midnames/sdk";
+
+   const result = await resolveDomain("alice.night");
+   console.log(result.data); // Address or contract
+   ```
+
+</Steps>
+
+That's it! The SDK is now ready for development purposes.
+
+## Basic Examples
+
+### Example 1: Resolve a Domain
+
+Translate a `.night` domain to its target address:
+
+```typescript
+import { resolveDomain } from "@midnames/sdk";
+
+async function resolveUserDomain(domain: string) {
+  const result = await resolveDomain(domain);
+
+  if (result.success) {
+    console.log("Resolved to:", result.data);
+    // => "mn_shield-cpk_test1..." or "0200..."
+  } else {
+    console.error("Resolution failed:", result.error.message);
+  }
+}
+
+await resolveUserDomain("alice.night");
+```
+
+### Example 2: Get Domain Profile
+
+Fetch complete profile data including fields and metadata:
+
+```typescript
+import { getDomainProfile } from "@midnames/sdk";
+
+async function fetchProfile(domain: string) {
+  const result = await getDomainProfile(domain);
+
+  if (!result.success) {
+    console.error("Error:", result.error.message);
+    return;
+  }
+
+  const profile = result.data;
+
+  console.log("Domain:", profile.fullDomain);
+  console.log("Owner:", profile.info?.owner);
+  console.log("Target:", profile.resolvedTarget);
+
+  // Access custom fields
+  console.log("Name:", profile.fields.get("name"));
+  console.log("Bio:", profile.fields.get("bio"));
+  console.log("Twitter:", profile.fields.get("twitter"));
+}
+
+await fetchProfile("alice.night");
+```
+
+### Example 3: Display Profile Widget (React)
+
+Show a beautiful profile card with zero configuration:
+
+```tsx
+import "@midnames/sdk/styles.css";
+import { DomainProfileWidget } from "@midnames/sdk/react/DomainProfileWidget";
+
+function ProfilePage() {
+  return (
+    <div>
+      <h1>User Profile</h1>
+      <DomainProfileWidget fullDomain="alice.night" />
+    </div>
+  );
+}
+```
+
+That's all you need! The widget automatically:
+
+- Fetches domain data
+- Displays avatar, bio, and social links
+- Shows ownership information
+- Handles errors gracefully
+
+## Common Use Cases
+
+### For DApp Developers
+
+#### Display user names instead of addresses
+
+```typescript
+import { resolveDomain } from "@midnames/sdk";
+
+// In your transaction UI
+async function displayRecipient(addressOrDomain: string) {
+  // If it looks like a domain, resolve it
+  if (addressOrDomain.endsWith(".night")) {
+    const result = await resolveDomain(addressOrDomain);
+    if (result.success) {
+      return {
+        displayName: addressOrDomain,
+        address: result.data,
+      };
+    }
+  }
+
+  return {
+    displayName: `${addressOrDomain.slice(0, 10)}...`,
+    address: addressOrDomain,
+  };
+}
+
+// Usage
+const recipient = await displayRecipient("alice.night");
+console.log(`Sending to ${recipient.displayName} (${recipient.address})`);
+```
+
+#### Reverse resolution (address → domain)
+
+While the SDK doesn't provide direct reverse resolution, you can implement it by storing mappings in your application or querying all domains.
+
+### For Wallet Developers
+
+#### Autocomplete domain search
+
+```typescript
+import { getDomainInfo, normalizeDomain } from "@midnames/sdk";
+
+async function isDomainAvailable(input: string): Promise<boolean> {
+  const domain = normalizeDomain(input);
+  const result = await getDomainInfo(domain);
+
+  // Domain is available if info is null
+  return !result.success || result.data.info === null;
+}
+
+// Usage
+const available = await isDomainAvailable("alice");
+console.log(available ? "Available!" : "Taken");
+```
+
+#### Show domain profile in wallet
+
+```tsx
+import { DomainProfileWidget } from "@midnames/sdk/react/DomainProfileWidget";
+
+function WalletContactCard({ domain }: { domain: string }) {
+  return (
+    <DomainProfileWidget
+      fullDomain={domain}
+      variant="compact"
+      showCopyButtons={true}
+      onCopySuccess={(field, value) => {
+        showToast(`Copied ${field}`);
+      }}
+    />
+  );
+}
+```
+
+## Error Handling
+
+All SDK functions implement a `Result` type for type-safe error handling, ensuring developers write clean, maintainable & predictable code:
+
+```typescript
+import { resolveDomain } from "@midnames/sdk";
+
+const result = await resolveDomain("alice.night");
+
+if (result.success) {
+  // Type: string (the resolved address)
+  console.log("Success:", result.data);
+} else {
+  // Type: MidnamesError
+  console.error("Error:", result.error);
+  console.error("Code:", result.error.code);
+  console.error("Message:", result.error.message);
+}
+```
+
+**Common error codes:**
+
+| Code                 | Meaning               | Action                   |
+| -------------------- | --------------------- | ------------------------ |
+| `DOMAIN_NOT_FOUND`   | Domain doesn't exist  | Show "Available" UI      |
+| `INVALID_DOMAIN`     | Invalid format        | Show validation error    |
+| `NETWORK_ERROR`      | Connection failed     | Retry or show offline UI |
+| `CONTRACT_NOT_FOUND` | Contract not deployed | Handle as not found      |
+
+## Advanced Configuration
+
+### Custom Provider
+
+By default, the SDK connects to Midnight TestNet. The SDK allows developers to easily customize his prefered provider:
+
+```typescript
+import { createDefaultProvider, resolveDomain } from "@midnames/sdk";
+import { NetworkId } from "@midnight-ntwrk/midnight-js-network-id";
+
+// Create custom provider
+const provider = createDefaultProvider({
+  indexerUrl: "https://your-indexer.example.com/api/v1/graphql",
+  indexerWsUrl: "wss://your-indexer.example.com/api/v1/graphql/ws",
+  networkId: NetworkId.TestNet,
+});
+
+// Use it
+const result = await resolveDomain("alice.night", { provider });
+```
+
+### Set Default Provider Globally
+
+```typescript
+import { setDefaultProvider, createDefaultProvider } from "@midnames/sdk";
+
+// Set once at app initialization
+const provider = createDefaultProvider();
+setDefaultProvider(provider);
+
+// Now all SDK functions use this provider by default
+```
+
+## Next Steps
+
+Now that you know the basics, explore these topics:
+
+<div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(250px, 1fr)); gap: 1rem; margin-top: 1rem;">
+
+**📖 Learn More**
+
+- [Domain Resolution](/reference/resolve/) - Complete guide to reading domain data
+- [Profile Widget](/reference/widget/) - Customize the React component
+- [Domain Operations](/reference/operations/) - Write operations (requires wallet)
+
+**🛠️ Guides**
+
+- [Buy a .night domain](/guides/buy_domain/) - Get your own domain
+- [Update domain fields](/guides/update_fields/) - Customize your profile
+- [Transfer domains](/guides/transfer_domain/) - Transfer ownership
+
+**📚 Reference**
+
+- [Utility Functions](/reference/utils/) - Helper functions for validation
+- [MNS Specification](/guides/valid_domains/) - Domain naming rules
+- [Types Reference](/reference/types/) - TypeScript type definitions
+
+</div>
+
+## Example Projects
+
+### Minimal DApp Integration
+
+A simple CLI DApp to visualize a Midnight Network stored profile through Midnames SDK tools. 
+
+```typescript
+// app.ts
+import { getDomainProfile } from "@midnames/sdk";
+
+async function main() {
+  const domain = process.argv[2] || "alice.night";
+  const result = await getDomainProfile(domain);
+
+  if (!result.success) {
+    console.error("Error:", result.error.message);
+    process.exit(1);
+  }
+
+  const { fullDomain, resolvedTarget, info, fields } = result.data;
+
+  console.log(` === ${fullDomain} === `);
+  console.log(` Owner: ${info?.owner || "N/A"}`);
+  console.log(` Target: ${resolvedTarget  || "N/A"}`);
+  console.log(` Name: ${fields.get("name") || "N/A"}`);
+  console.log(` Bio: ${fields.get("bio") || "N/A"}`);
+  console.log(` Website: ${fields.get("website") || "N/A"}`);
+}
+
+main();
+```
+
+```bash
+# Run it
+npx ts-node app.ts foo.night
+```
+
+### React App with Widget
+
+```tsx
+// App.tsx
+import { useState } from "react";
+import "@midnames/sdk/styles.css";
+import { DomainProfileWidget } from "@midnames/sdk/react/DomainProfileWidget";
+
+export default function App() {
+  const [domain, setDomain] = useState("alice.night");
+
+  return (
+    <div style={{ padding: "2rem", maxWidth: "600px", margin: "0 auto" }}>
+      <h1>Midnames Profile Viewer</h1>
+
+      <input
+        type="text"
+        value={domain}
+        onChange={(e) => setDomain(e.target.value)}
+        placeholder="Enter a .night domain"
+        style={{ width: "100%", padding: "0.5rem", marginBottom: "1rem" }}
+      />
+
+      <DomainProfileWidget
+        fullDomain={domain}
+        variant="full"
+        onError={(error) => {
+          console.error("Widget error:", error);
+        }}
+      />
+    </div>
+  );
+}
+```
+
+## Troubleshooting
+
+### "Domain not found" for valid domains
+
+- Check that you're using the correct network with your wallet provider (TestNet vs MainNet)
+- Verify the domain is actually registered at [ns.midnames.com](https://ns.midnames.com)
+- Ensure `.night` TLD is included (use `normalizeDomain()` helper)
+
+### React widget not styling correctly
+
+- Make sure you imported the CSS: `import '@midnames/sdk/styles.css'`
+- Check for CSS conflicts with your app's global styles
+- Try wrapping in a container with `className` to isolate styles
+
+### TypeScript errors
+
+- Ensure you have `@midnight-ntwrk` peer dependencies installed
+- Check your `tsconfig.json` has `"moduleResolution": "bundler"` or `"node"`
+- Import types explicitly if needed: `import type { DomainProfileData } from '@midnames/sdk'`
+
+### Network connection issues
+
+- Verify your internet connection
+- Check if the indexer is accessible (default: `https://indexer.testnet-02.midnight.network`)
+- Try with a custom provider to rule out default configuration issues
+
+## Community & Support
+
+- **Documentation**: [https://docs.midnames.com](/)
+- **GitHub**: [https://github.com/midnames/sdk](https://github.com/midnames/sdk)
+- **Issues**: [Report bugs](https://github.com/midnames/sdk/issues)
+
+Ready to dive deeper? Check out the [complete API reference](/reference/) or explore specific [guides](/guides/).
diff --git a/src/content/docs/guides/transfer_domain.mdx b/src/content/docs/guides/transfer_domain.mdx
index a4a5aaf..967d593 100644
--- a/src/content/docs/guides/transfer_domain.mdx
+++ b/src/content/docs/guides/transfer_domain.mdx
@@ -21,6 +21,7 @@ Ensure you have:
 
 - <a href="https://docs.midnight.network/develop/tutorial/using/chrome-ext" target="_blank">Lace Wallet for Midnight</a> installed
 - The wallet address of the recipient
+- Enough funds in your wallet to sign your transaction
 
 ## Transfer Process
 
@@ -71,6 +72,11 @@ Ensure you have:
     ![Domain transfer confirmation pop-up](../../../assets/domain_transfer/domain-transfer-popup.png)
 </Steps>
 
+   <Aside type="note" title="Important: transaction timing">
+   **Don't panic!** Midnight transactions take up to two minutes due to its ZK-proof generation. So you can relax and enjoy your coffee while the transaction is being finalized.
+   </Aside>
+
+
 ## Common Issues
 
 **Transfer failed?**
diff --git a/src/content/docs/guides/update_fields.mdx b/src/content/docs/guides/update_fields.mdx
index 58eefed..01f72d3 100644
--- a/src/content/docs/guides/update_fields.mdx
+++ b/src/content/docs/guides/update_fields.mdx
@@ -1,6 +1,431 @@
 ---
-title: Update fields in a domain
-description: Learn how to update the records in a domain in Midnight
+title: Update Domain Fields
+description: Learn how to update custom fields in your .night domain
 sidebar:
-  label: Update fields in a domain
+  label: Update Domain Fields
 ---
+
+import { Aside, Steps } from "@astrojs/starlight/components";
+
+Learn how to update custom fields in your `.night` domain using the Midnames SDK. Fields allow you to store profile information, social links, and metadata on-chain.
+
+## What are Domain Fields?
+
+Domain fields are key-value pairs stored in your domain's contract. They allow you to:
+
+- Store profile information (name, bio, avatar, banner)
+- Add social media links (Twitter, GitHub, website, etc.)
+- Set privacy settings (encryption public key)
+- Store custom metadata specific to your application
+
+<Aside type="tip">
+  Fields are publicly readable but only writable by the domain owner. This makes them perfect for public profile information.
+</Aside>
+
+## Standard Fields
+
+These fields are recognized across the Midnames ecosystem:
+
+| Field      | Purpose                            | Example                   |
+| ---------- | -----------------------------------| ------------------------- |
+| `name`     | Display name                       | `"Alice Cooper"`          |
+| `bio`      | Short biography                    | `"Web3 Developer"`        |
+| `avatar`   | HTTPS URL or Contract Address/IPFS |  see [Avatar Types](/reference/resolve/#avatar-types)          |
+| `website`  | Personal website                   | `"https://alice.dev"`     |
+| `twitter`  | Twitter handle                     | `"@alice"` or `"alice"`   |
+| `github`   | GitHub username                    | `"alice"`                 |
+| `location` | Location                           | `"San Francisco"`         |
+| `epk`      | Encryption public key              | `"mn_shield-epk_test..."` |
+| `email`    | Email address                      | `"alice@example.com"`     |
+| `discord`  | Discord handle                     | `"alice#1234"`            |
+| `telegram` | Telegram username                  | `"@alice"`                |
+
+<Aside type="note">
+  You can also create custom fields for application-specific data. There's no limit to the field names you can use.
+</Aside>
+
+## Prerequisites
+
+To update fields, you need:
+
+1. **Lace Wallet** installed and funded ([Get Lace](https://docs.midnight.network/develop/tutorial/using/chrome-ext))
+2. **Domain ownership** - You must own the domain to update its fields
+3. **Funded wallet** for blockchain transactions
+4. **SDK setup** with wallet providers (see [Domain Operations](/reference/operations/#prerequisites))
+
+## Update a Single Field
+
+### Using the SDK
+
+```typescript
+import { insertField } from '@midnames/sdk';
+
+async function updateBio(domain: string, providers) {
+  const result = await insertField(
+    domain,
+    'bio',
+    'Web3 Developer | Midnight Enthusiast',
+    providers
+  );
+
+  if (result.success) {
+    console.log('Field updated!', result.data.transactionId);
+  } else {
+    console.error('Update failed:', result.error.message);
+  }
+}
+
+await updateBio('alice.night', providers);
+```
+
+### Common Updates
+
+```typescript
+// Update profile name
+await insertField('alice.night', 'name', 'Alice Cooper', providers);
+
+// Set avatar
+await insertField('alice.night', 'avatar', 'https://avatars.example.com/alice.png', providers);
+
+// Add Twitter
+await insertField('alice.night', 'twitter', '@alice', providers);
+
+// Add website
+await insertField('alice.night', 'website', 'https://alice.dev', providers);
+
+// Set encryption key
+await insertField('alice.night', 'epk', 'mn_shield-epk_test1...', providers);
+```
+
+## Update Multiple Fields
+
+For efficiency, Midnames SDK provides batch addition for multiple fields in a single transaction:
+
+```typescript
+import { addMultipleFields } from '@midnames/sdk';
+
+async function setupProfile(domain: string, providers) {
+  const fields: Array<[string, string]> = [
+    ['name', 'Alice Cooper'],
+    ['bio', 'Web3 Developer | Midnight Enthusiast'],
+    ['avatar', 'https://avatars.example.com/alice.png'],
+    ['website', 'https://alice.dev'],
+    ['twitter', '@alice'],
+    ['github', 'alice'],
+    ['location', 'San Francisco'],
+  ];
+
+  const result = await addMultipleFields(domain, fields, providers);
+
+  if (result.success) {
+    console.log('Profile setup complete!', result.data.transactionId);
+  } else {
+    console.error('Setup failed:', result.error.message);
+  }
+}
+
+await setupProfile('alice.night', providers);
+```
+
+<Aside type="tip">
+  **Maximum 10 fields per transaction.** If you need to set more, split them into multiple `addMultipleFields()` calls. Take a look at [Best Practices](/guides/update_fields/#best-practices) for more tips.
+</Aside>
+
+## Remove Fields
+
+### Remove a specific field
+
+```typescript
+import { clearField } from '@midnames/sdk';
+
+// Remove Twitter link
+const result = await clearField('alice.night', 'twitter', providers);
+
+if (result.success) {
+  console.log('Field removed:', result.data.transactionId);
+}
+```
+
+### Remove all fields
+
+```typescript
+import { clearAllFields } from '@midnames/sdk';
+
+// Clear entire profile
+const result = await clearAllFields('alice.night', providers);
+
+if (result.success) {
+  console.log('All fields cleared:', result.data.transactionId);
+}
+```
+
+<Aside type="caution">
+  **Warning:** `clearAllFields()` removes ALL custom fields from your domain. This action cannot be undone. Your domain name and ownership remain unchanged.
+</Aside>
+
+## Complete Example: Profile Manager
+
+Here's a full React component for managing domain fields:
+
+```tsx
+import { useState } from 'react';
+import { insertField, getDomainProfile } from '@midnames/sdk';
+import type { ContractProviders } from '@midnight-ntwrk/midnight-js-contracts';
+
+function ProfileEditor({ domain, providers }: {
+  domain: string;
+  providers: ContractProviders;
+}) {
+  const [name, setName] = useState('');
+  const [bio, setBio] = useState('');
+  const [twitter, setTwitter] = useState('');
+  const [loading, setLoading] = useState(false);
+
+  const handleSave = async () => {
+    setLoading(true);
+
+    try {
+      // Update each field
+      if (name) {
+        const result = await insertField(domain, 'name', name, providers);
+        if (!result.success) throw result.error;
+      }
+
+      if (bio) {
+        const result = await insertField(domain, 'bio', bio, providers);
+        if (!result.success) throw result.error;
+      }
+
+      if (twitter) {
+        const result = await insertField(domain, 'twitter', twitter, providers);
+        if (!result.success) throw result.error;
+      }
+
+      alert('Profile updated successfully!');
+    } catch (error) {
+      console.error('Update failed:', error);
+      alert('Update failed. See console for details.');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div style={{ maxWidth: '500px', margin: '0 auto', padding: '2rem' }}>
+      <h2>Edit Profile: {domain}</h2>
+
+      <div style={{ marginBottom: '1rem' }}>
+        <label>Name</label>
+        <input
+          type="text"
+          value={name}
+          onChange={(e) => setName(e.target.value)}
+          placeholder="Your display name"
+          style={{ width: '100%', padding: '0.5rem' }}
+        />
+      </div>
+
+      <div style={{ marginBottom: '1rem' }}>
+        <label>Bio</label>
+        <textarea
+          value={bio}
+          onChange={(e) => setBio(e.target.value)}
+          placeholder="Tell us about yourself"
+          style={{ width: '100%', padding: '0.5rem', minHeight: '100px' }}
+        />
+      </div>
+
+      <div style={{ marginBottom: '1rem' }}>
+        <label>Twitter</label>
+        <input
+          type="text"
+          value={twitter}
+          onChange={(e) => setTwitter(e.target.value)}
+          placeholder="@username"
+          style={{ width: '100%', padding: '0.5rem' }}
+        />
+      </div>
+
+      <button
+        onClick={handleSave}
+        disabled={loading}
+        style={{
+          padding: '0.75rem 1.5rem',
+          background: '#6366f1',
+          color: 'white',
+          border: 'none',
+          borderRadius: '0.5rem',
+          cursor: loading ? 'not-allowed' : 'pointer',
+        }}
+      >
+        {loading ? 'Updating...' : 'Save Profile'}
+      </button>
+    </div>
+  );
+}
+```
+
+## Using Midnames Web App
+
+You can also update fields through the Midnames web interface at [ns.midnames.com](https://ns.midnames.com):
+
+<Steps>
+
+1. **Connect your wallet**
+
+   Visit [ns.midnames.com](https://ns.midnames.com) and connect your Lace wallet
+
+2. **Search for your domain**
+
+   Enter your domain name in the search bar
+
+3. **Click "Edit Profile"**
+
+   You'll see an edit interface with all available fields
+
+4. **Update fields**
+
+   Fill in any fields you want to update or modify
+
+5. **Save changes**
+
+   Click "Save" and sign the transaction with your wallet
+
+</Steps>
+
+<Aside type="tip">
+  Using the web app is the easiest way to update fields if you're not integrating into your own application.
+</Aside>
+
+## Best Practices
+
+### 1. Use Standard Field Names
+
+Stick to standard field names when possible for maximum compatibility:
+
+```typescript
+// Good - recognized by all MNS apps. Easy to remember.
+await insertField('alice.night', 'twitter', '@alice', providers);
+
+// Less ideal - custom field name. Hard to remember or query.
+await insertField('alice.night', 'twitter_handle', '@alice', providers);
+```
+
+### 2. Validate Before Updating
+
+```typescript
+import { getDomainInfo } from '@midnames/sdk';
+
+async function safeUpdateField(domain: string, key: string, value: string, providers, myAddress: string) {
+  // Verify ownership first
+  const info = await getDomainInfo(domain);
+
+  if (!info.success || info.data.owner !== myAddress) {
+    throw new Error('You do not own this domain');
+  }
+
+  // Now safe to update
+  return await insertField(domain, key, value, providers);
+}
+```
+
+### 3. Batch Updates for Efficiency
+
+```typescript
+// Less efficient - 3 separate transactions, gas for each transaction.
+await insertField('alice.night', 'name', 'Alice', providers);
+await insertField('alice.night', 'bio', 'Developer', providers);
+await insertField('alice.night', 'twitter', '@alice', providers);
+
+// More efficient - single transaction, less gas.
+await addMultipleFields('alice.night', [
+  ['name', 'Alice'],
+  ['bio', 'Developer'],
+  ['twitter', '@alice'],
+], providers);
+```
+
+### 4. Handle Errors Gracefully
+
+```typescript
+async function updateFieldWithFeedback(domain: string, key: string, value: string, providers: PublicDataProviders) {
+  const result = await insertField(domain, key, value, providers);
+
+  if (result.success) {
+    showSuccessToast(`${key} updated!`);
+    return result.data.transactionId;
+  } else {
+    // Handle specific errors
+    switch (result.error.code) {
+      case 'NETWORK_ERROR':
+        showErrorToast('Network error. Please try again.');
+        break;
+      case 'DOMAIN_NOT_FOUND':
+        showErrorToast('Domain not found.');
+        break;
+      default:
+        showErrorToast(`Update failed: ${result.error.message}`);
+    }
+    return null;
+  }
+}
+```
+
+## Field Value Formats
+
+### Avatar URLs
+
+Avatars support multiple formats:
+
+```typescript
+// Standard URL
+await insertField('alice.night', 'avatar', 'https://example.com/avatar.png', providers);
+
+// IPFS
+await insertField('alice.night', 'avatar', 'ipfs://Qm123abc...', providers);
+
+// Midnight NFT Contract <contractAddress>:<tokenId> format
+await insertField('alice.night', 'avatar', '0200abc123...:42', providers);
+```
+
+### Social Media Handles
+
+```typescript
+// Twitter - with or without @
+await insertField('alice.night', 'twitter', '@alice', providers);
+await insertField('alice.night', 'twitter', 'alice', providers); // Both work
+
+// GitHub - username only
+await insertField('alice.night', 'github', 'alice', providers);
+
+// Website - include protocol
+await insertField('alice.night', 'website', 'https://alice.dev', providers);
+```
+
+## Troubleshooting
+
+**Transaction fails immediately**
+- Verify you own the domain
+- Check wallet balance (need funds for gas fee)
+- Ensure wallet is connected and unlocked
+
+**Field doesn't appear after update**
+- Wait for transaction confirmation (can take 10-30 seconds)
+- Refresh the page or re-query the domain
+- Check transaction succeeded by viewing on block explorer
+
+**"DOMAIN_NOT_FOUND" error**
+- Verify domain is correctly formatted: `alice.night`
+- Check domain actually exists (query with `getDomainInfo`)
+- Ensure you're on the correct network (TestNet vs MainNet)
+
+**Contact Support**
+- Midnames provides a 24/7 <a href= "mailto:support@midnames.com"> customer support email </a> service for further troubleshooting enquiries. 
+
+## Next Steps
+
+- Learn about [domain operations](/reference/operations/) for more advanced write operations
+- Explore the [Profile Widget](/reference/widget/) to display your updated fields
+- Read the [Domain Transfer Guide](/guides/transfer_domain/) to transfer domains
+
+Ready to customize your profile? Head over to [ns.midnames.com](https://ns.midnames.com) or integrate the SDK into your app!
diff --git a/src/content/docs/guides/valid_domains.mdx b/src/content/docs/guides/valid_domains.mdx
index a6de683..22dbf46 100644
--- a/src/content/docs/guides/valid_domains.mdx
+++ b/src/content/docs/guides/valid_domains.mdx
@@ -68,4 +68,4 @@ The following domains are all reserved and cannot be registered:
 
 # Caveats
 
-All domain parts are valid in the contracts but the frontend (and more importantly the SDK for wallet integration) will restrict the user to only create and resolve domains that follow the above specification.
+All domain parts are valid at the contract level; however, the frontend—and more importantly, the SDK used for wallet integration—will limit users to creating and resolving domains that comply with the specification above.
\ No newline at end of file
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx
index 677ad5a..ee92a4c 100644
--- a/src/content/docs/index.mdx
+++ b/src/content/docs/index.mdx
@@ -8,18 +8,33 @@ hero:
     file: ../../assets/houston.webp
   actions:
     - text: Read the docs
-      link: /guides/buy_domain/
+      link: /guides/quickstart/
       icon: right-arrow
 ---
 
 import { CardGrid, LinkCard } from "@astrojs/starlight/components";
 
 <CardGrid>
+  <LinkCard
+    title="Quick Start"
+    description="Get started with the Midnames SDK in 5 minutes. Perfect for DApp and wallet developers."
+    href="/guides/quickstart/"
+  />
   <LinkCard
     title="Buy a .night domain"
-    description="Get your own .night domain to represent your identity on the Midnight Network."
+    description="Get your own .night domain to store your identity on the Midnight Network."
     href="/guides/buy_domain/"
   />
+  <LinkCard
+    title="Domain Resolution"
+    description="Learn how to resolve .night domains to addresses and query profile information using the SDK."
+    href="/reference/resolve/"
+  />
+  <LinkCard
+    title="Profile Widget"
+    description="Display interactive domain profiles in your DApp with the pre-built widget component."
+    href="/reference/widget/"
+  />
   <LinkCard
     title="Transfer a .night domain"
     description="Easily transfer your .night domain to another user on the Midnight Network."
@@ -27,12 +42,17 @@ import { CardGrid, LinkCard } from "@astrojs/starlight/components";
   />
   <LinkCard
     title="Update fields in a domain"
-    description="Learn how to update the fields associated with your .night domain."
+    description="Learn how to update profile information, social links, and custom metadata."
     href="/guides/update_fields/"
   />
+  <LinkCard
+    title="Domain Operations"
+    description="Complete guide to write operations: manage fields, transfer ownership, and register subdomains."
+    href="/reference/operations/"
+  />
   <LinkCard
     title="MNS Specification"
-    description="Understand the rules and specifications for valid .night domains."
+    description="Understand the rules and specifications for valid .night domain names."
     href="/guides/valid_domains/"
-  ></LinkCard>
+  />
 </CardGrid>
diff --git a/src/content/docs/reference/index.mdx b/src/content/docs/reference/index.mdx
index dd148f8..7c8b50f 100644
--- a/src/content/docs/reference/index.mdx
+++ b/src/content/docs/reference/index.mdx
@@ -1,10 +1,93 @@
 ---
 title: SDK Reference
-description: Here are some references to start using the Midnames SDK.
+description: Complete API reference for the Midnames SDK
 sidebar:
   hidden: true
 ---
 
-Here are some references to start using the Midnames SDK.
+import { CardGrid, LinkCard } from "@astrojs/starlight/components";
 
-Look through the list on the left to find a guide that suits your needs.
+Complete API documentation for the Midnames SDK. Learn how to resolve domains, manage domain operations, display profile widgets, and use utility functions.
+
+## Core Functionality
+
+<CardGrid>
+  <LinkCard
+    title="Domain Resolution"
+    description="Query domain data, resolve names to addresses, and fetch profile information."
+    href="/reference/resolve/"
+  />
+  <LinkCard
+    title="Domain Operations"
+    description="Write operations for managing domains: update fields, transfer ownership, register subdomains."
+    href="/reference/operations/"
+  />
+</CardGrid>
+
+## Components & UI
+
+<CardGrid>
+  <LinkCard
+    title="Profile Widget"
+    description="Pre-built React component for displaying beautiful domain profiles with full customization."
+    href="/reference/widget/"
+  />
+</CardGrid>
+
+## Utilities & Helpers
+
+<CardGrid>
+  <LinkCard
+    title="Utility Functions"
+    description="Helper functions for domain validation, normalization, parsing, and address formatting."
+    href="/reference/utils/"
+  />
+  <LinkCard
+    title="TypeScript Types"
+    description="Complete TypeScript type definitions, interfaces, and error types."
+    href="/reference/types/"
+  />
+</CardGrid>
+
+## Quick Links
+
+- **New to the SDK?** Start with the [Quick Start Guide](/guides/quickstart/)
+- **Need examples?** Check out the code examples in each reference page
+- **Looking for guides?** Visit the [Guides section](/guides/)
+
+## Installation
+
+```bash
+npm install @midnames/sdk
+```
+
+For React components:
+
+```bash
+npm install @midnames/sdk react react-dom lucide-react
+```
+
+## Basic Usage
+
+```typescript
+import { resolveDomain, getDomainProfile } from "@midnames/sdk";
+
+// Resolve a domain
+const result = await resolveDomain("alice.night");
+if (result.success) {
+  console.log("Address:", result.data);
+}
+
+// Get full profile
+const profile = await getDomainProfile("alice.night");
+if (profile.success) {
+  console.log("Name:", profile.data.fields.get("name"));
+  console.log("Bio:", profile.data.fields.get("bio"));
+}
+```
+
+## Support
+
+- **Documentation**: Browse through the reference pages on the left
+- **GitHub**: [https://github.com/midnames/sdk](https://github.com/midnames/sdk)
+- **Issues**: [Report bugs or request features](https://github.com/midnames/sdk/issues)
diff --git a/src/content/docs/reference/operations.mdx b/src/content/docs/reference/operations.mdx
new file mode 100644
index 0000000..0225bdd
--- /dev/null
+++ b/src/content/docs/reference/operations.mdx
@@ -0,0 +1,854 @@
+---
+title: Domain Operations
+description: Write operations for managing .night domains
+sidebar:
+  label: Domain Operations
+---
+
+import { Aside, Code } from "@astrojs/starlight/components";
+
+Learn how to perform write operations on `.night` domains, including field management, transfers, and subdomain registration. These operations require a connected wallet with the Midnight SDK.
+
+<Aside type="caution">
+  Write operations require: - A connected wallet (via Lace or similar) -
+  Sufficient funds for transaction fees - The appropriate permissions (domain
+  owner or parent domain owner)
+</Aside>
+
+The SDK provides the following write operations:
+
+**Field Management:**
+
+- `insertField()` - Add or update a single field
+- `clearField()` - Remove a specific field
+- `clearAllFields()` - Remove all fields
+- `addMultipleFields()` - Add up to 10 fields at once
+
+**Domain Management:**
+
+- `updateDomainTarget()` - Change where the domain resolves to
+- `changeDomainOwner()` - Transfer ownership (executed on domain contract)
+- `transferDomainOwnership()` - Transfer ownership (executed on parent contract)
+
+**Subdomain Operations:**
+
+- `registerDomainFor()` - Register a subdomain (free for parent owner)
+- `buyDomainFor()` - Purchase a subdomain (requires payment)
+
+**Settings:**
+
+- `updateDomainCost()` - Change subdomain pricing
+- `updateDomainColor()` - Change accepted token type
+- `setDomainResolver()` - Update resolver contract
+
+## Prerequisites
+
+### Setup Wallet Providers
+
+All write operations require `ContractProviders` which include your wallet connection:
+
+```typescript
+import { type ContractProviders } from "@midnight-ntwrk/midnight-js-contracts";
+import { leafContractInstance } from "@midnames/sdk";
+
+// Your wallet setup (example using Midnight wallet API)
+const providers: ContractProviders<typeof leafContractInstance> = {
+  privateStateProvider: myPrivateStateProvider,
+  ContractProviders: myContractProviders,
+  walletProvider: myWalletProvider,
+  zkConfigProvider: myZkConfigProvider,
+};
+```
+
+<Aside type="note">
+  The exact wallet setup depends on your application architecture. Refer to the{" "}
+  <a href="https://docs.midnight.network" target="_blank">
+    Midnight Network documentation
+  </a>{" "}
+for wallet integration details.
+</Aside>
+
+## Field Management
+
+
+
+
+
+
+
+
+### Insert or Update a Field
+
+Add or update a single field in your domain: {" "}
+
+**Signature:**
+
+```typescript
+async function insertField(domain: string, key: string, value: string, providers: ContractProviders): Promise<Result<{ transactionId: string}>>
+```
+
+**Parameters:**
+
+- `domain` (string) - The .night domain name to modify (e.g., "alice.night")
+- `key` (string) - The field name/key to insert or update (e.g., "twitter", "bio")
+- `value` (string) - The field value to set
+- `providers` (ContractProviders) - Wallet and provider instances for transaction signing
+
+**Returns:**
+
+A `Result<{ transactionId: string}>` containing either:
+- `success: true` with `data` containing the transaction details including `transactionId`
+- `success: false` with an `error` object containing the error details
+
+```typescript
+import { insertField } from "@midnames/sdk";
+
+const result = await insertField(
+  "alice.night", // Your domain
+  "twitter", // Field key
+  "@alice", // Field value
+  providers // Wallet providers
+);
+
+if (result.success) {
+  console.log("Transaction ID:", result.data.transactionId);
+} else {
+  console.error("Failed:", result.error.message);
+}
+```
+
+**Common use cases:**
+
+```typescript
+// Update profile information
+await insertField("alice.night", "name", "Alice Cooper", providers);
+await insertField("alice.night", "bio", "Web3 developer", providers);
+await insertField(
+  "alice.night",
+  "avatar",
+  "https://example.com/avatar.png",
+  providers
+);
+
+// Add social links
+await insertField("alice.night", "twitter", "@alice", providers);
+await insertField("alice.night", "github", "alice", providers);
+await insertField("alice.night", "website", "https://alice.dev", providers);
+
+// Set encryption key for shielded addresses
+await insertField("alice.night", "epk", "mn_shield-epk_test1...", providers);
+```
+
+
+
+
+
+
+
+
+### Add Multiple Fields at Once
+
+Add up to 10 fields in a single transaction (more efficient than multiple `insertField` calls): {" "}
+
+**Signature:**
+
+```typescript
+async function addMultipleFields(domain: string, fields: Array<[string, string]>, providers: ContractProviders): Promise<Result<{ transactionId: string }>>
+```
+
+**Parameters:**
+
+- `domain` (string) - The .night domain name to modify
+- `fields` (Array[(string, string)]) - Array of [key, value] tuples, up to 10 entries
+- `providers` (ContractProviders) - Wallet and provider instances for transaction signing
+
+**Returns:**
+
+A `Result<{ transactionId: string }>` containing either:
+- `success: true` with `data` containing the transaction details including `transactionId`
+- `success: false` with an `error` object containing the error details
+
+```typescript
+import { addMultipleFields } from "@midnames/sdk";
+
+const fields: Array<[string, string]> = [
+  ["name", "Alice Cooper"],
+  ["bio", "Web3 developer & educator"],
+  ["avatar", "https://example.com/avatar.png"],
+  ["twitter", "@alice"],
+  ["github", "alice"],
+  ["website", "https://alice.dev"],
+];
+
+const result = await addMultipleFields("alice.night", fields, providers);
+
+if (result.success) {
+  console.log("All fields added!", result.data.transactionId);
+}
+```
+
+<Aside type="tip">
+  `addMultipleFields()` is more gas-efficient than calling `insertField()`
+  multiple times. Use it when setting up a new profile or bulk-updating fields.
+</Aside>
+
+
+
+
+
+
+
+
+### Clear a Specific Field
+
+Remove a field from your domain: {" "}
+
+**Signature:**
+
+```typescript
+async function clearField(domain: string, key: string, providers: ContractProviders): Promise<Result<{ transactionId: string }>>
+```
+
+**Parameters:**
+
+- `domain` (string) - The .night domain name to modify
+- `key` (string) - The field name/key to remove
+- `providers` (ContractProviders) - Wallet and provider instances for transaction signing
+
+**Returns:**
+
+A `Result<{ transactionId: string }>` containing either:
+- `success: true` with `data` containing the transaction details including `transactionId`
+- `success: false` with an `error` object containing the error details
+
+```typescript
+import { clearField } from "@midnames/sdk";
+
+const result = await clearField("alice.night", "twitter", providers);
+
+if (result.success) {
+  console.log("Field cleared:", result.data.transactionId);
+}
+```
+
+
+
+
+
+
+
+
+### Clear All Fields
+
+Remove all custom fields from your domain: {" "}
+
+**Signature:**
+
+```typescript
+async function clearAllFields(domain: string, providers: ContractProviders): Promise<Result<{ transactionId: string }>>
+```
+
+**Parameters:**
+
+- `domain` (string) - The .night domain name to modify
+- `providers` (ContractProviders) - Wallet and provider instances for transaction signing
+
+**Returns:**
+
+A `Result<{ transactionId: string }>` containing either:
+- `success: true` with `data` containing the transaction details including `transactionId`
+- `success: false` with an `error` object containing the error details
+
+```typescript
+import { clearAllFields } from "@midnames/sdk";
+
+const result = await clearAllFields("alice.night", providers);
+
+if (result.success) {
+  console.log("All fields cleared:", result.data.transactionId);
+}
+```
+
+
+
+
+
+
+
+## Domain Target Management
+
+### Update Domain Target
+
+Change where your domain resolves to. The target can be either a wallet address or a contract address: {" "}
+
+**Signature:**
+
+```typescript
+async function updateDomainTarget(domain: string, target: string, providers: ContractProviders): Promise<Result<{ transactionId: string }>>
+```
+
+**Parameters:**
+
+- `domain` (string) - The .night domain name to modify
+- `target` (string) - The target address (wallet address starting with "mn_" or contract address starting with "0200" or "0x")
+- `providers` (ContractProviders) - Wallet and provider instances for transaction signing
+
+**Returns:**
+
+A `Result<{ transactionId: string }>` containing either:
+- `success: true` with `data` containing the transaction details including `transactionId`
+- `success: false` with an `error` object containing the error details
+
+```typescript
+import { updateDomainTarget } from "@midnames/sdk";
+
+// Point to a wallet address
+const result1 = await updateDomainTarget(
+  "alice.night",
+  "mn_shield-cpk_test1abc...", // Wallet address
+  providers
+);
+
+// Or point to a contract address
+const result2 = await updateDomainTarget(
+  "alice.night",
+  "0200abc123...", // Contract address
+  providers
+);
+```
+
+<Aside type="note">
+  The SDK automatically detects whether the target is a wallet address (starts
+  with `mn_`) or contract address (starts with `0200` or `0x`).
+</Aside>
+
+
+
+
+
+
+
+## Ownership Transfer
+
+### Transfer Domain Ownership (Method 1)
+
+Transfer ownership using the parent domain's contract: {" "}
+
+**Signature:**
+
+```typescript
+async function transferDomainOwnership(parent: string, subdomain: string, new_owner: string, providers: ContractProviders): Promise<Result<{ transactionId: string }>>
+```
+
+**Parameters:**
+
+- `parent` (string) - The parent domain name (e.g., "night" for "alice.night")
+- `subdomain` (string) - The subdomain name without the parent (e.g., "alice")
+- `new_owner` (string) - The wallet address of the new owner
+- `providers` (ContractProviders) - Wallet and provider instances for transaction signing
+
+**Returns:**
+
+A `Result<{ transactionId: string }>` containing either:
+- `success: true` with `data` containing the transaction details including `transactionId`
+- `success: false` with an `error` object containing the error details
+
+```typescript
+import { transferDomainOwnership } from "@midnames/sdk";
+
+const result = await transferDomainOwnership(
+  "night", // Parent domain
+  "alice", // Subdomain name
+  "mn_shield-cpk_test1xyz...", // New owner's address
+  providers
+);
+
+if (result.success) {
+  console.log("Transfer complete:", result.data.transactionId);
+}
+```
+
+<Aside type="danger">
+  **Transfers are permanent!** Double-check the recipient address before
+  confirming. Once transferred, you lose ownership and cannot reverse the
+  transaction.
+</Aside>
+
+
+
+
+
+
+
+### Change Domain Owner (Method 2)
+
+Transfer ownership using the domain's own contract: {" "}
+
+**Signature:**
+
+```typescript
+async function changeDomainOwner(domain: string, new_owner: string, providers: ContractProviders): Promise<Result<{ transactionId: string }>>
+```
+
+**Parameters:**
+
+- `domain` (string) - The full domain name to transfer (e.g., "alice.night")
+- `new_owner` (string) - The wallet address of the new owner
+- `providers` (ContractProviders) - Wallet and provider instances for transaction signing
+
+**Returns:**
+
+A `Result<{ transactionId: string }>` containing either:
+- `success: true` with `data` containing the transaction details including `transactionId`
+- `success: false` with an `error` object containing the error details
+
+```typescript
+import { changeDomainOwner } from "@midnames/sdk";
+
+const result = await changeDomainOwner(
+  "alice.night",
+  "mn_shield-cpk_test1xyz...", // New owner's address
+  providers
+);
+```
+
+**When to use each method:**
+
+- Use `transferDomainOwnership()` when you own the parent domain
+- Use `changeDomainOwner()` when you own the domain itself
+
+
+
+
+
+
+
+## Subdomain Registration
+
+### Register Subdomain (Free)
+
+As a domain owner, you can register subdomains for free: {" "}
+
+**Signature:**
+
+```typescript
+async function registerDomainFor(parent_domain: string, target_owner: string, subdomain: string, resolver: string, providers: ContractProviders): Promise<Result<{ transactionId: string }>>
+```
+
+**Parameters:**
+
+- `parent_domain` (string) - The parent domain you own (e.g., "alice.night")
+- `target_owner` (string) - The wallet address of the subdomain owner
+- `subdomain` (string) - The subdomain name to register (e.g., "work")
+- `resolver` (string) - The resolver contract address
+- `providers` (ContractProviders) - Wallet and provider instances for transaction signing
+
+**Returns:**
+
+A `Result<{ transactionId: string }>` containing either:
+- `success: true` with `data` containing the transaction details including `transactionId`
+- `success: false` with an `error` object containing the error details
+
+```typescript
+import { registerDomainFor } from "@midnames/sdk";
+
+const result = await registerDomainFor(
+  "alice.night", // Parent domain you own
+  "mn_shield-cpk_test1bob...", // Subdomain owner address
+  "work", // Subdomain name
+  "0200contract123...", // Resolver contract address
+  providers
+);
+
+// This creates: work.alice.night
+```
+
+<Aside type="tip">
+  Parent domain owners can register subdomains for free without requiring
+  payment, making it easy to create hierarchical domain structures.
+</Aside>
+
+
+
+
+
+
+
+### Buy Subdomain (Paid)
+
+Purchase a subdomain when you're not the parent owner: {" "}
+
+**Signature:**
+
+```typescript
+async function buyDomainFor(parent_domain: string, subdomain_owner: string, name: string, resolver: string, tokens: bigint, providers: ContractProviders): Promise<Result<{ transactionId: string }>>
+```
+
+**Parameters:**
+
+- `parent_domain` (string) - The parent domain (e.g., "alice.night")
+- `subdomain_owner` (string) - The wallet address of the subdomain owner
+- `name` (string) - The subdomain name to purchase (e.g., "blog")
+- `resolver` (string) - The resolver contract address
+- `tokens` (bigint) - Payment amount that must match the parent domain's `domainCost` setting
+- `providers` (ContractProviders) - Wallet and provider instances for transaction signing
+
+**Returns:**
+
+A `Result<{ transactionId: string }>` containing either:
+- `success: true` with `data` containing the transaction details including `transactionId`
+- `success: false` with an `error` object containing the error details
+
+```typescript
+import { buyDomainFor } from "@midnames/sdk";
+
+const result = await buyDomainFor(
+  "alice.night", // Parent domain
+  "mn_shield-cpk_test1bob...", // Subdomain owner address
+  "blog", // Subdomain name
+  "0200contract456...", // Resolver contract address
+  BigInt(1000), // Payment amount
+  providers
+);
+
+// This creates: blog.alice.night
+```
+
+The payment amount must match the `domainCost` setting of the parent domain.
+
+
+
+
+
+
+
+## Domain Settings
+
+### Update Subdomain Pricing
+Change the cost for others to buy subdomains under your domain:
+
+**Signature:**
+
+```typescript
+async function updateDomainCost(domain: string, new_cost: bigint, providers: ContractProviders): Promise<Result<{ transactionId: string }>>
+```
+
+**Parameters:**
+
+- `domain` (string) - The domain name to update pricing for
+- `new_cost` (bigint) - The new cost in the smallest token unit (use `BigInt(0)` for free)
+- `providers` (ContractProviders) - Wallet and provider instances for transaction signing
+
+**Returns:**
+
+A `Result<{ transactionId: string }>` containing either:
+- `success: true` with `data` containing the transaction details including `transactionId`
+- `success: false` with an `error` object containing the error details
+
+```typescript
+import { updateDomainCost } from "@midnames/sdk";
+
+const result = await updateDomainCost(
+  "alice.night",
+  BigInt(5000), // New cost (in smallest token unit)
+  providers
+);
+```
+
+**Pricing strategy examples:**
+
+```typescript
+// Free subdomains
+await updateDomainCost("alice.night", BigInt(0), providers);
+
+// Paid subdomains
+await updateDomainCost("alice.night", BigInt(10000), providers);
+
+// Premium subdomains
+await updateDomainCost("premium.alice.night", BigInt(100000), providers);
+```
+
+
+
+
+
+
+
+### Update Accepted Token Type
+
+Change which token type is accepted for subdomain purchases:
+
+**Signature:**
+
+```typescript
+async function updateDomainColor(domain: string, colorBytes: Uint8Array, providers: ContractProviders): Promise<Result<{ transactionId: string }>>
+```
+
+**Parameters:**
+
+- `domain` (string) - The domain name to update token type for
+- `colorBytes` (Uint8Array) - A 32-byte Uint8Array representing the token identifier
+- `providers` (ContractProviders) - Wallet and provider instances for transaction signing
+
+**Returns:**
+
+A `Result<{ transactionId: string }>` containing either:
+- `success: true` with `data` containing the transaction details including `transactionId`
+- `success: false` with an `error` object containing the error details
+
+```typescript
+import { updateDomainColor } from "@midnames/sdk";
+
+// colorBytes must be a 32-byte Uint8Array representing the token identifier
+const colorBytes = new Uint8Array(32); // Your token color
+
+const result = await updateDomainColor("alice.night", colorBytes, providers);
+```
+
+<Aside type="note">
+  The "color" refers to the token identifier in Midnight's UTXO model. Most
+  users will use the native token (default).
+</Aside>
+
+
+
+
+
+
+
+### Set Domain Resolver
+
+Update the resolver contract for a subdomain: {" "}
+
+**Signature:**
+
+```typescript
+async function setDomainResolver(domain: string, subdomain_name: string, resolver: string, providers: ContractProviders): Promise<Result<{ transactionId: string }>>
+```
+
+**Parameters:**
+
+- `domain` (string) - The parent domain name (e.g., "alice.night")
+- `subdomain_name` (string) - The subdomain name without the parent (e.g., "work")
+- `resolver` (string) - The new resolver contract address
+- `providers` (ContractProviders) - Wallet and provider instances for transaction signing
+
+**Returns:**
+
+A `Result<{ transactionId: string }>` containing either:
+- `success: true` with `data` containing the transaction details including `transactionId`
+- `success: false` with an `error` object containing the error details
+
+```typescript
+import { setDomainResolver } from "@midnames/sdk";
+
+const result = await setDomainResolver(
+  "alice.night", // Parent domain
+  "work", // Subdomain name
+  "0200newResolver...", // New resolver address
+  providers
+);
+
+// Updates resolver for: work.alice.night
+```
+
+
+
+
+
+
+
+## Error Handling
+
+All operations return a `Result` type:
+
+```typescript
+const result = await insertField("alice.night", "name", "Alice", providers);
+
+if (!result.success) {
+  // Handle errors
+  console.error("Error code:", result.error.code);
+  console.error("Message:", result.error.message);
+
+  switch (result.error.code) {
+    case "NETWORK_ERROR":
+      console.log("Check your network connection");
+      break;
+    case "DOMAIN_NOT_FOUND":
+      console.log("Domain does not exist");
+      break;
+    default:
+      console.log("Unexpected error:", result.error);
+  }
+}
+```
+
+
+
+
+
+
+
+## Transaction Monitoring
+
+All successful operations return a transaction ID:
+
+```typescript
+const result = await insertField("alice.night", "bio", "Hello!", providers);
+
+if (result.success) {
+  const txId = result.data.transactionId;
+  console.log("Transaction submitted:", txId);
+
+  // You can use the Midnight indexer to check transaction status
+  // (exact implementation depends on your setup)
+}
+```
+
+
+
+
+
+
+
+## Best Practices & Recommendations
+
+### 1. Batch Field Updates
+
+Use `addMultipleFields()` instead of multiple `insertField()` calls:
+
+```typescript
+// Less efficient (3 transactions)
+await insertField("alice.night", "name", "Alice", providers);
+await insertField("alice.night", "bio", "Developer", providers);
+await insertField("alice.night", "twitter", "@alice", providers);
+
+// More efficient (1 transaction)
+await addMultipleFields(
+  "alice.night",
+  [
+    ["name", "Alice"],
+    ["bio", "Developer"],
+    ["twitter", "@alice"],
+  ],
+  providers
+);
+```
+
+### 2. Verify Ownership Before Operations
+
+```typescript
+import { getDomainInfo } from "@midnames/sdk";
+
+const info = await getDomainInfo("alice.night");
+if (info.success && info.data.owner === myWalletAddress) {
+  // Safe to proceed with write operations
+  await insertField("alice.night", "bio", "Updated!", providers);
+}
+```
+
+### 3. Handle Transaction Failures Gracefully
+
+```typescript
+async function updateFieldWithRetry(
+  domain: string,
+  key: string,
+  value: string,
+  maxRetries = 3
+) {
+  for (let i = 0; i < maxRetries; i++) {
+    const result = await insertField(domain, key, value, providers);
+
+    if (result.success) {
+      return result.data.transactionId;
+    }
+
+    if (result.error.code !== "NETWORK_ERROR") {
+      // Non-retryable error
+      throw result.error;
+    }
+
+    // Wait before retry
+    await new Promise((resolve) => setTimeout(resolve, 2000 * (i + 1)));
+  }
+
+  throw new Error("Max retries exceeded");
+}
+```
+
+## Complete Example
+
+Here's a full example of setting up a domain profile:
+
+```typescript
+import {
+  addMultipleFields,
+  updateDomainTarget,
+  updateDomainCost,
+} from "@midnames/sdk";
+
+async function setupDomainProfile(
+  domain: string,
+  providers: ContractProviders
+) {
+  // 1. Set up profile fields
+  const fieldsResult = await addMultipleFields(
+    domain,
+    [
+      ["name", "Alice Cooper"],
+      ["bio", "Web3 Developer | Midnight Enthusiast"],
+      ["avatar", "https://avatars.example.com/alice.png"],
+      ["website", "https://alice.dev"],
+      ["twitter", "@alice"],
+      ["github", "alice"],
+      ["epk", "mn_shield-epk_test1..."],
+    ],
+    providers
+  );
+
+  if (!fieldsResult.success) {
+    console.error("Failed to set fields:", fieldsResult.error);
+    return;
+  }
+
+  console.log("Profile fields set:", fieldsResult.data.transactionId);
+
+  // 2. Set domain target
+  const targetResult = await updateDomainTarget(
+    domain,
+    "mn_shield-cpk_test1abc...",
+    providers
+  );
+
+  if (!targetResult.success) {
+    console.error("Failed to set target:", targetResult.error);
+    return;
+  }
+
+  console.log("Target updated:", targetResult.data.transactionId);
+
+  // 3. Configure subdomain pricing
+  const costResult = await updateDomainCost(
+    domain,
+    BigInt(1000), // Charge 1000 for subdomains
+    providers
+  );
+
+  if (!costResult.success) {
+    console.error("Failed to set cost:", costResult.error);
+    return;
+  }
+
+  console.log("Subdomain pricing set:", costResult.data.transactionId);
+  console.log("Domain setup complete!");
+}
+
+// Usage
+await setupDomainProfile("alice.night", providers);
+```
+
+## Next Steps
+
+- Learn about [domain resolution](/reference/resolve/) for reading domain data
+- Explore [utility functions](/reference/utils/) for domain validation and formatting
+- Check the [error handling guide](/reference/types/#error-types) for comprehensive error management
diff --git a/src/content/docs/reference/resolve.mdx b/src/content/docs/reference/resolve.mdx
index 174606a..c997ef5 100644
--- a/src/content/docs/reference/resolve.mdx
+++ b/src/content/docs/reference/resolve.mdx
@@ -1,4 +1,407 @@
 ---
 title: Resolve a .night domain
 description: How to use the SDK to resolve a .night domain.
+sidebar:
+  label: Domain Resolution
 ---
+
+import { Aside, Code, Tabs, TabItem } from "@astrojs/starlight/components";
+
+Learn how to resolve `.night` domains to their target addresses using the Midnames SDK. Domain resolution is the core functionality that allows you to translate human-readable names into blockchain addresses.
+
+The SDK provides several functions for reading domain data:
+
+- **`resolveDomain()`** - Resolve a domain to its target address
+- **`getDomainInfo()`** - Get ownership and resolver information
+- **`getDomainProfile()`** - Get complete profile data including fields
+- **`getDomainFields()`** - Get custom fields stored in a domain
+- **`getDomainSettings()`** - Get domain settings (cost, coin color)
+
+## Installation
+
+```bash
+npm install @midnames/sdk
+```
+
+## Basic Domain Resolution
+
+### Resolve a domain to its target address
+
+The `resolveDomain()` function returns the target address that a domain points to.
+
+**Signature:**
+
+```typescript
+async function resolveDomain(domain: string, options?: ResolveOptions): Promise<Result<string>>
+```
+
+**Parameters:**
+
+- `domain` (string) - The .night domain name to resolve (e.g., "alice.night")
+- `options` (optional) - Configuration object:
+  - `provider` - Custom provider instance for connecting to a specific network
+
+**Returns:**
+
+A `Result<string>` containing either:
+- `success: true` with `data` being the resolved target address (CoinPublicKey or shielded address)
+- `success: false` with an `error` object containing the error details
+
+```typescript
+import { resolveDomain } from '@midnames/sdk';
+
+// Resolve a domain
+const result = await resolveDomain('alice.night');
+
+if (result.success) {
+  console.log('Target address:', result.data);
+  // Output: mn_shield-cpk_test1... or 0200...
+} else {
+  console.error('Error:', result.error.message);
+}
+```
+
+<Aside type="tip">
+  All SDK functions return a `Result` type that contains either `success: true`
+  with `data`, or `success: false` with an `error`. This pattern ensures
+  type-safe error handling.
+</Aside>
+
+### Using a custom provider
+
+By default, the SDK connects to the Midnight TestNet. You can provide a custom provider:
+
+```typescript
+import { resolveDomain, createDefaultProvider } from "@midnames/sdk";
+import { NetworkId } from "@midnight-ntwrk/midnight-js-network-id";
+
+// Create a custom provider
+const provider = createDefaultProvider({
+  indexerUrl: "https://your-indexer.example.com/api/v1/graphql",
+  indexerWsUrl: "wss://your-indexer.example.com/api/v1/graphql/ws",
+  networkId: NetworkId.TestNet,
+});
+
+// Use it for resolution
+const result = await resolveDomain("alice.night", { provider });
+```
+
+## Get Domain Information
+
+### Get ownership and resolver details
+
+**Signature:**
+
+```typescript
+async function getDomainInfo(domain: string, options?: ResolveOptions): Promise<Result<DomainInfo>>
+```
+
+**Parameters:**
+
+- `domain` (string) - The .night domain name to query
+- `options` (optional) - Configuration object:
+  - `provider` - Custom provider instance for connecting to a specific network
+
+**Returns:**
+
+A `Result<DomainInfo>` containing either:
+- `success: true` with `data` being the domain ownership information
+- `success: false` with an `error` object containing the error details
+
+```typescript
+import { getDomainInfo } from "@midnames/sdk";
+
+const result = await getDomainInfo("alice.night");
+
+if (result.success) {
+  const { owner, resolver, contractAddress } = result.data;
+  console.log("Owner:", owner); // Wallet address
+  console.log("Resolver:", resolver); // Contract address
+  console.log("Contract:", contractAddress); // Parent contract
+}
+```
+
+**Return type:**
+
+```typescript
+interface DomainInfo {
+  owner: string; // The wallet address that owns the domain
+  resolver: string; // The contract address that resolves the domain
+  contractAddress?: string; // The parent contract address
+}
+```
+
+## Get Complete Domain Profile
+
+### Fetch all domain data in one call
+
+The `getDomainProfile()` function aggregates all domain information including custom fields:
+
+**Signature:**
+
+```typescript
+async function getDomainProfile(domain: string, options?: ResolveOptions): Promise<Result<DomainProfileData>>
+```
+
+**Parameters:**
+
+- `domain` (string) - The .night domain name to query
+- `options` (optional) - Configuration object:
+  - `provider` - Custom provider instance for connecting to a specific network
+
+**Returns:**
+
+A `Result<DomainProfileData>` containing either:
+- `success: true` with `data` being the complete domain profile including target, ownership info, custom fields, and settings
+- `success: false` with an `error` object containing the error details
+
+```typescript
+import { getDomainProfile } from "@midnames/sdk";
+
+const result = await getDomainProfile("id.alice.night");
+
+if (result.success) {
+  const profile = result.data;
+
+  console.log("Domain:", profile.fullDomain);
+  console.log("Target:", profile.resolvedTarget);
+  console.log("Owner:", profile.info?.owner);
+
+  // Access custom fields
+  const name = profile.fields.get("name");
+  const bio = profile.fields.get("bio");
+  const avatar = profile.fields.get("avatar");
+  const twitter = profile.fields.get("twitter");
+
+  console.log("Name:", name);
+  console.log("Bio:", bio);
+}
+```
+
+**Return type:**
+
+```typescript
+interface DomainProfileData {
+  fullDomain: string; // Normalized domain name
+  resolvedTarget: string | null; // Target address or null
+  info: DomainInfo | null; // Ownership info or null
+  fields: Map<string, string>; // Custom fields as key-value pairs
+  settings: DomainSettings | null; // Domain settings or null
+}
+```
+
+### Common Profile Fields
+
+These fields are recognized by the MidNames ecosystem:
+
+| Field      | Description                              | Example                   |
+| ---------- | ---------------------------------------- | ------------------------- |
+| `name`     | Display name                             | `"Alice"`                 |
+| `bio`      | Short biography                          | `"Web3 developer"`        |
+| `avatar`   | Midnight Contract Address or IPFS or URL | `see below`               |
+| `website`  | Personal website                         | `"alice.dev"`             |
+| `twitter`  | Twitter handle                           | `"@alice"`                |
+| `github`   | GitHub username                          | `"alice"`                 |
+| `location` | Location                                 | `"San Francisco"`         |
+| `epk`      | Encryption public key                    | `"mn_shield-epk_test..."` |
+
+<Aside type="note">
+  The `epk` field is special: when combined with a `CoinPublicKey` target, it
+  automatically derives a full shielded address (`mn_shield-addr_test...`).
+</Aside>
+
+## Avatar Types
+
+The `avatar` field supports multiple input formats.  
+This flexibility lets developers choose between centralized URLs, decentralized IPFS assets, or on-chain contract references.
+
+| Type                  | Description                                                                                              | Format Example                                                 |
+| --------------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| **URL**               | Direct link to an image hosted on the web.                                                               | `"https://example.com/avatar.png"`                             |
+| **IPFS**              | Reference to a decentralized image on IPFS (can include a gateway).                                      | `"ipfs://Qm123abc..."` or `"https://ipfs.io/ipfs/Qm123abc..."` |
+| **Midnight Contract** | On-chain avatar reference stored in a Midnight NFT contract, formatted as `<contractAddress>:<tokenId>`. | `"0200abc123def456...:42"`                                     |
+
+:::note
+If a contract-based avatar is provided, **Starlight automatically resolves** the NFT metadata and retrieves the associated image.
+:::
+
+## Get Domain Fields
+
+### Retrieve custom fields only
+
+**Signature:**
+
+```typescript
+async function getDomainFields(contractAddress: string, options?: ResolveOptions): Promise<Result<Map<string, string>>>
+```
+
+**Parameters:**
+
+- `contractAddress` (string) - The contract address of the domain (in hex format starting with "0200...")
+- `options` (optional) - Configuration object:
+  - `provider` - Custom provider instance for connecting to a specific network
+
+**Returns:**
+
+A `Result<Map<string, string>>` containing either:
+- `success: true` with `data` being a Map of field names to their string values
+- `success: false` with an `error` object containing the error details
+
+```typescript
+import { getDomainFields } from "@midnames/sdk";
+
+// Get fields directly from a contract address
+const result = await getDomainFields("0200abc...");
+
+if (result.success) {
+  const fields = result.data;
+
+  for (const [key, value] of fields) {
+    console.log(`${key}: ${value}`);
+  }
+}
+```
+
+## Get Domain Settings
+
+### Query subdomain pricing and token type
+
+**Signature:**
+
+```typescript
+async function getDomainSettings(contractAddress: string, options?: ResolveOptions): Promise<Result<DomainSettings>>
+```
+
+**Parameters:**
+
+- `contractAddress` (string) - The contract address of the domain (in hex format starting with "0200...")
+- `options` (optional) - Configuration object:
+  - `provider` - Custom provider instance for connecting to a specific network
+
+**Returns:**
+
+A `Result<DomainSettings>` containing either:
+- `success: true` with `data` being the domain settings including accepted token type and subdomain registration cost
+- `success: false` with an `error` object containing the error details
+
+```typescript
+import { getDomainSettings } from "@midnames/sdk";
+
+const result = await getDomainSettings("0200abc...");
+
+if (result.success) {
+  const { coinColor, domainCost } = result.data;
+
+  console.log("Accepted token:", coinColor);
+  console.log("Subdomain cost:", domainCost);
+  // domainCost is a BigInt representing the price in the smallest unit
+}
+```
+
+**Return type:**
+
+```typescript
+interface DomainSettings {
+  coinColor: Uint8Array; // 32-byte token identifier
+  domainCost: bigint; // Price to register subdomains
+}
+```
+
+## Subdomain Resolution
+
+The SDK automatically handles subdomain hierarchy:
+
+```typescript
+// All of these work seamlessly
+await resolveDomain("alice.night"); // Top-level domain
+await resolveDomain("id.alice.night"); // Subdomain
+await resolveDomain("work.id.alice.night"); // Nested subdomain
+```
+
+<Aside type="tip">
+  You can create unlimited subdomain levels. Each subdomain is a separate
+  contract that can have its own fields, settings, and subdomains.
+</Aside>
+
+## Error Handling
+
+All SDK functions return a `Result` type for safe error handling:
+
+```typescript
+const result = await resolveDomain("invalid..domain.night");
+
+if (!result.success) {
+  console.error("Error code:", result.error.code);
+  console.error("Message:", result.error.message);
+
+  // Handle specific error types
+  switch (result.error.code) {
+    case "DOMAIN_NOT_FOUND":
+      console.log("Domain does not exist");
+      break;
+    case "INVALID_DOMAIN":
+      console.log("Domain format is invalid");
+      break;
+    case "NETWORK_ERROR":
+      console.log("Network connection failed");
+      break;
+  }
+}
+```
+
+### Error Types
+
+| Error Code           | Description                                    |
+| -------------------- | ---------------------------------------------- |
+| `DOMAIN_NOT_FOUND`   | Domain doesn't exist or hasn't been registered |
+| `INVALID_DOMAIN`     | Domain format doesn't match validation rules   |
+| `CONTRACT_NOT_FOUND` | Contract address not found on-chain            |
+| `NETWORK_ERROR`      | Network or provider connection error           |
+| `PROVIDER_ERROR`     | Issue with the data provider                   |
+
+## Complete Example
+
+Here's a full example showing domain resolution in a DApp:
+
+```typescript
+import { getDomainProfile, createDefaultProvider } from "@midnames/sdk";
+
+async function displayUserProfile(domain: string) {
+  const provider = createDefaultProvider();
+  const result = await getDomainProfile(domain, { provider });
+
+  if (!result.success) {
+    console.error(`Failed to load ${domain}:`, result.error.message);
+    return;
+  }
+
+  const profile = result.data;
+
+  // Check if domain exists
+  if (!profile.info) {
+    console.log(`${domain} is available!`);
+    return;
+  }
+
+  // Display profile information
+  console.log(`
+    Domain: ${profile.fullDomain}
+    Owner: ${profile.info.owner}
+    Target: ${profile.resolvedTarget || "Not set"}
+
+    Profile:
+    - Name: ${profile.fields.get("name") || "N/A"}
+    - Bio: ${profile.fields.get("bio") || "N/A"}
+    - Website: ${profile.fields.get("website") || "N/A"}
+  `);
+}
+
+// Usage
+await displayUserProfile("alice.night");
+```
+
+## Next Steps
+
+- Learn how to [update domain fields](/guides/update_fields/)
+- Explore the [Domain Profile Widget](/reference/widget/) for React applications
+- Read about [domain operations](/reference/operations/) for write operations
diff --git a/src/content/docs/reference/types.mdx b/src/content/docs/reference/types.mdx
new file mode 100644
index 0000000..dee9980
--- /dev/null
+++ b/src/content/docs/reference/types.mdx
@@ -0,0 +1,545 @@
+---
+title: TypeScript Types
+description: Complete TypeScript type definitions for the Midnames SDK
+sidebar:
+  label: TypeScript Types
+---
+
+import { Aside } from "@astrojs/starlight/components";
+
+Complete reference of TypeScript types, interfaces, and enums used in the Midnames SDK. All types are exported and available for import.
+
+## Core Types
+
+### Result pattern
+
+The SDK uses a `Result<T>` pattern for type-safe error handling. All SDK functions return a `Result` type.
+
+```typescript
+type Result<T, E = MidnamesError> =
+  | { success: true; data: T; error?: never }
+  | { success: false; data?: never; error: E };
+```
+
+**Usage:**
+
+```typescript
+import type { Result } from '@midnames/sdk';
+
+const result: Result<string> = await resolveDomain('alice.night');
+
+if (result.success) {
+  // TypeScript knows result.data is string
+  console.log(result.data);
+} else {
+  // TypeScript knows result.error is MidnamesError
+  console.error(result.error.message);
+}
+```
+
+## Domain Data Types
+
+### DomainInfo
+
+Information about domain ownership and resolver.
+
+```typescript
+interface DomainInfo {
+  owner: string;           // Wallet address of the domain owner
+  resolver: string;        // Contract address that resolves the domain
+  contractAddress?: string; // Parent contract address (optional)
+}
+```
+
+**Example:**
+
+```typescript
+import type { DomainInfo } from '@midnames/sdk';
+
+const info: DomainInfo = {
+  owner: 'mn_shield-cpk_test1abc...',
+  resolver: '0200def456...',
+  contractAddress: '020052aede...',
+};
+```
+
+### DomainSettings
+
+Configuration settings for a domain contract.
+
+```typescript
+interface DomainSettings {
+  coinColor: Uint8Array;  // 32-byte token identifier
+  domainCost: bigint;     // Cost to register subdomains (in smallest unit)
+}
+```
+
+**Example:**
+
+```typescript
+import type { DomainSettings } from '@midnames/sdk';
+
+const settings: DomainSettings = {
+  coinColor: new Uint8Array(32),
+  domainCost: BigInt(1000),
+};
+```
+
+### DomainProfileData
+
+Complete profile data including all fields and metadata.
+
+```typescript
+interface DomainProfileData {
+  fullDomain: string;              // Normalized domain name (e.g., "alice.night")
+  resolvedTarget: string | null;   // Target address or null if not set
+  info: DomainInfo | null;         // Ownership info or null if domain doesn't exist
+  fields: Map<string, string>;     // Custom fields as key-value pairs
+  settings: DomainSettings | null; // Domain settings or null if unavailable
+}
+```
+
+**Example:**
+
+```typescript
+import type { DomainProfileData } from '@midnames/sdk';
+
+const profile: DomainProfileData = {
+  fullDomain: 'alice.night',
+  resolvedTarget: 'mn_shield-cpk_test1...',
+  info: {
+    owner: 'mn_shield-cpk_test1...',
+    resolver: '0200abc...',
+  },
+  fields: new Map([
+    ['name', 'Alice Cooper'],
+    ['bio', 'Web3 Developer'],
+    ['twitter', '@alice'],
+  ]),
+  settings: {
+    coinColor: new Uint8Array(32),
+    domainCost: BigInt(0),
+  },
+};
+```
+
+### ParsedDomain
+
+Result of parsing a domain string into its components.
+
+```typescript
+interface ParsedDomain {
+  isValid: boolean;         // Whether the domain format is valid
+  domainName: string;       // The leftmost label (e.g., "alice" from "alice.night")
+  parentDomainPath: string; // Everything after the first label (e.g., "night")
+  fullDomain: string;       // The normalized full domain
+  depth: number;            // Number of labels excluding TLD
+}
+```
+
+**Example:**
+
+```typescript
+import type { ParsedDomain } from '@midnames/sdk/utils/domain';
+
+const parsed: ParsedDomain = {
+  isValid: true,
+  domainName: 'work',
+  parentDomainPath: 'id.alice.night',
+  fullDomain: 'work.id.alice.night',
+  depth: 3,
+};
+```
+
+## Error Types
+
+### MidnamesError
+
+Base error class for all SDK errors.
+
+```typescript
+class MidnamesError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly details?: unknown
+  );
+
+  name: 'MidnamesError';
+  message: string;
+  code: string;
+  details?: unknown;
+}
+```
+
+**Properties:**
+
+- `name` - Always `'MidnamesError'`
+- `message` - Human-readable error description
+- `code` - Machine-readable error code
+- `details` - Optional additional error context
+
+### NetworkError
+
+Network or connection-related errors.
+
+```typescript
+class NetworkError extends MidnamesError {
+  constructor(message: string, details?: unknown);
+
+  name: 'NetworkError';
+  code: 'NETWORK_ERROR';
+}
+```
+
+### ContractNotFoundError
+
+Contract address not found on-chain.
+
+```typescript
+class ContractNotFoundError extends MidnamesError {
+  constructor(contractAddress: string, details?: unknown);
+
+  name: 'ContractNotFoundError';
+  code: 'CONTRACT_NOT_FOUND';
+}
+```
+
+### DomainNotFoundError
+
+Domain doesn't exist or hasn't been registered.
+
+```typescript
+class DomainNotFoundError extends MidnamesError {
+  constructor(domain: string, details?: unknown);
+
+  name: 'DomainNotFoundError';
+  code: 'DOMAIN_NOT_FOUND';
+}
+```
+
+### InvalidDomainError
+
+Domain format is invalid.
+
+```typescript
+class InvalidDomainError extends MidnamesError {
+  constructor(domain: string, reason: string, details?: unknown);
+
+  name: 'InvalidDomainError';
+  code: 'INVALID_DOMAIN';
+}
+```
+
+### ProviderError
+
+Issue with the data provider.
+
+```typescript
+class ProviderError extends MidnamesError {
+  constructor(message: string, details?: unknown);
+
+  name: 'ProviderError';
+  code: 'PROVIDER_ERROR';
+}
+```
+
+**Error Code Reference:**
+
+| Code | Error Class | When it occurs |
+|------|-------------|----------------|
+| `NETWORK_ERROR` | `NetworkError` | Connection or network issues |
+| `CONTRACT_NOT_FOUND` | `ContractNotFoundError` | Contract doesn't exist on-chain |
+| `DOMAIN_NOT_FOUND` | `DomainNotFoundError` | Domain not registered |
+| `INVALID_DOMAIN` | `InvalidDomainError` | Domain format validation failed |
+| `PROVIDER_ERROR` | `ProviderError` | Data provider malfunction |
+
+## React Component Types
+
+### DomainProfileWidgetProps
+
+Props for the `DomainProfileWidget` React component.
+
+```typescript
+type DomainProfileWidgetProps = {
+  // Required
+  fullDomain: string;
+
+  // Provider
+  publicDataProvider?: PublicDataProvider;
+
+  // Layout & Styling
+  className?: string;
+  variant?: 'full' | 'compact' | 'inline' | 'minimal';
+  theme?: 'light' | 'dark' | 'auto';
+  borderRadius?: 'none' | 'sm' | 'md' | 'lg';
+  padding?: 'none' | 'sm' | 'md' | 'lg';
+
+  // Visibility Controls
+  showStatus?: boolean;
+  showBanner?: boolean;
+  showAvatar?: boolean;
+  showBio?: boolean;
+  showDomainInfo?: boolean;
+  showSocialLinks?: boolean;
+  showCopyButtons?: boolean;
+
+  // Field Selection
+  fields?: Array<'target' | 'owner' | 'resolver'>;
+  customFields?: string[];
+
+  // Event Handlers
+  onError?: (error: MidnamesError) => void;
+  onFieldClick?: (field: string, value: string) => void;
+  onCopySuccess?: (field: string, value: string) => void;
+
+  // Custom Rendering
+  renderActions?: (data: DomainProfileData | null) => React.ReactNode;
+};
+```
+
+**Example:**
+
+```typescript
+import type { DomainProfileWidgetProps } from '@midnames/sdk/react/DomainProfileWidget';
+
+const props: DomainProfileWidgetProps = {
+  fullDomain: 'alice.night',
+  variant: 'compact',
+  theme: 'dark',
+  showCopyButtons: true,
+  onCopySuccess: (field, value) => console.log(`Copied ${field}`),
+};
+```
+
+## Provider Types
+
+### ProviderConfig
+
+Configuration for creating a custom provider.
+
+```typescript
+interface ProviderConfig {
+  indexerUrl?: string;       // GraphQL endpoint URL
+  indexerWsUrl?: string;     // WebSocket endpoint URL
+  networkId?: NetworkId;     // Network to connect to
+}
+```
+
+**Example:**
+
+```typescript
+import type { ProviderConfig } from '@midnames/sdk';
+import { NetworkId } from '@midnight-ntwrk/midnight-js-network-id';
+
+const config: ProviderConfig = {
+  indexerUrl: 'https://indexer.testnet-02.midnight.network/api/v1/graphql',
+  indexerWsUrl: 'wss://indexer.testnet-02.midnight.network/api/v1/graphql/ws',
+  networkId: NetworkId.TestNet,
+};
+```
+
+## External Types
+
+These types come from Midnight SDK peer dependencies:
+
+### PublicDataProvider
+
+```typescript
+import type { PublicDataProvider } from '@midnight-ntwrk/midnight-js-types';
+```
+
+Used for querying blockchain data.
+
+### ContractProviders
+
+```typescript
+import type { ContractProviders } from '@midnight-ntwrk/midnight-js-contracts';
+```
+
+Required for write operations (includes wallet connection).
+
+### NetworkId
+
+```typescript
+import { NetworkId } from '@midnight-ntwrk/midnight-js-network-id';
+
+enum NetworkId {
+  Undeployed = 'undeployed',
+  TestNet = 'testnet',
+}
+```
+
+## Utility Type Helpers
+
+### Result Helpers
+
+```typescript
+// Create success result
+function success<T>(data: T): Result<T>;
+
+// Create failure result
+function failure<E>(error: E): Result<never, E>;
+
+// Pattern match on result
+function match<T, E, U>(
+  result: Result<T, E>,
+  patterns: {
+    success: (data: T) => U;
+    error: (error: E) => U;
+  }
+): U;
+
+// Transform success value
+function map<T, U, E>(
+  result: Result<T, E>,
+  fn: (data: T) => U
+): Result<U, E>;
+
+// Chain operations
+function flatMap<T, U, E>(
+  result: Result<T, E>,
+  fn: (data: T) => Result<U, E>
+): Result<U, E>;
+```
+
+**Example:**
+
+```typescript
+import { success, failure, match } from '@midnames/sdk';
+
+const result = success('alice.night');
+
+const message = match(result, {
+  success: (domain) => `Found: ${domain}`,
+  error: (err) => `Error: ${err.message}`,
+});
+
+console.log(message); // "Found: alice.night"
+```
+
+## Type Guards
+
+### Checking Result Success
+
+```typescript
+const result = await resolveDomain('alice.night');
+
+if (result.success) {
+  // TypeScript narrows type automatically
+  const address: string = result.data;
+} else {
+  const error: MidnamesError = result.error;
+}
+```
+
+### Checking Error Type
+
+```typescript
+import { DomainNotFoundError } from '@midnames/sdk';
+
+const result = await getDomainInfo('alice.night');
+
+if (!result.success) {
+  if (result.error instanceof DomainNotFoundError) {
+    console.log('Domain not found');
+  } else {
+    console.log('Other error:', result.error.code);
+  }
+}
+```
+
+## Generic Type Parameters
+
+### Custom Result Error Types
+
+```typescript
+import type { Result } from '@midnames/sdk';
+
+// Result with custom error type
+type MyResult<T> = Result<T, MyCustomError>;
+
+class MyCustomError extends Error {
+  constructor(public code: string) {
+    super();
+  }
+}
+```
+
+## Import Patterns
+
+### Named Imports
+
+```typescript
+// Core types
+import type { DomainInfo, DomainProfileData, DomainSettings } from '@midnames/sdk';
+
+// Error types
+import { MidnamesError, DomainNotFoundError, NetworkError } from '@midnames/sdk';
+
+// Result utilities
+import { success, failure, match, map } from '@midnames/sdk';
+
+// Domain utilities
+import type { ParsedDomain } from '@midnames/sdk/utils/domain';
+
+// React types
+import type { DomainProfileWidgetProps } from '@midnames/sdk/react/DomainProfileWidget';
+```
+
+### Default Imports
+
+```typescript
+// React components
+import { DomainProfileWidget } from '@midnames/sdk/react/DomainProfileWidget';
+```
+
+## Type-Safe Patterns
+
+### Type guards for domain validation
+
+```typescript
+import { parseFullDomain, isValidDomainName } from '@midnames/sdk';
+
+function validateDomain(input: string): input is string {
+  const parsed = parseFullDomain(input);
+  return parsed.isValid && isValidDomainName(parsed.domainName);
+}
+
+// Usage
+if (validateDomain(userInput)) {
+  // userInput is guaranteed to be a valid domain
+  await resolveDomain(userInput);
+}
+```
+
+### Exhaustive error handling
+
+```typescript
+function handleError(error: MidnamesError): string {
+  switch (error.code) {
+    case 'DOMAIN_NOT_FOUND':
+      return 'Domain not found';
+    case 'NETWORK_ERROR':
+      return 'Network error';
+    case 'INVALID_DOMAIN':
+      return 'Invalid domain format';
+    case 'CONTRACT_NOT_FOUND':
+      return 'Contract not found';
+    case 'PROVIDER_ERROR':
+      return 'Provider error';
+    default:
+      // TypeScript ensures this is never reached
+      const _exhaustive: never = error.code;
+      return 'Unknown error';
+  }
+}
+```
+
+## Next Steps
+
+- Review [domain resolution](/reference/resolve/) for using these types in practice
+- Explore [utility functions](/reference/utils/) for type-safe helpers
+- Check the [error handling guide](/reference/types/#error-types) for error management patterns
+
+All types are fully documented with JSDoc comments in the source code for IDE autocomplete and inline documentation.
diff --git a/src/content/docs/reference/utils.mdx b/src/content/docs/reference/utils.mdx
new file mode 100644
index 0000000..4690fda
--- /dev/null
+++ b/src/content/docs/reference/utils.mdx
@@ -0,0 +1,488 @@
+---
+title: Utility Functions
+description: Helper functions for domain validation, formatting, and address handling
+sidebar:
+  label: Utility Functions
+---
+
+import { Aside, Code } from "@astrojs/starlight/components";
+
+The SDK includes utility functions for domain name validation, normalization, parsing, and address formatting. These helpers are useful when building domain-aware applications.
+
+## Domain Utilities
+
+Import from `@midnames/sdk/utils/domain`:
+
+```typescript
+import {
+  normalizeDomain,
+  parseFullDomain,
+  isValidDomainName,
+  getParentDomain,
+  getSubdomain,
+  buildFullDomain,
+  buildTraversalPath,
+  isTLD,
+} from '@midnames/sdk/utils/domain';
+```
+
+### normalizeDomain()
+
+Normalizes a domain string by cleaning and standardizing the format.
+
+**Signature:**
+
+```typescript
+function normalizeDomain(input: string, assumeTld?: boolean): string
+```
+
+**Parameters:**
+
+- `input` - The domain string to normalize
+- `assumeTld` - (optional, default: `true`) Whether to automatically append `.night` if missing
+
+**Returns:** Normalized domain string in lowercase with standard formatting
+
+**Examples:**
+
+```typescript
+normalizeDomain('Alice.Night');
+// => 'alice.night'
+
+normalizeDomain('ALICE');
+// => 'alice.night' (auto-appends .night)
+
+normalizeDomain('alice', false);
+// => 'alice' (doesn't append .night)
+
+normalizeDomain('alice..night');
+// => 'alice.night' (removes double dots)
+
+normalizeDomain('  alice.night.  ');
+// => 'alice.night' (trims whitespace)
+```
+
+<Aside type="tip">
+  Always use `normalizeDomain()` before passing user input to SDK functions. It ensures consistent formatting and prevents common mistakes.
+</Aside>
+
+### parseFullDomain()
+
+Parses a full domain into its components.
+
+**Signature:**
+
+```typescript
+function parseFullDomain(fullDomain: string, tld?: string): ParsedDomain
+
+interface ParsedDomain {
+  isValid: boolean;
+  domainName: string;      // The leftmost label
+  parentDomainPath: string; // Everything after the first label
+  fullDomain: string;       // The normalized full domain
+  depth: number;            // Number of labels (excluding TLD)
+}
+```
+
+**Parameters:**
+
+- `fullDomain` - The domain to parse
+- `tld` - (optional, default: `'night'`) The TLD to expect
+
+**Examples:**
+
+```typescript
+parseFullDomain('alice.night');
+// {
+//   isValid: true,
+//   domainName: 'alice',
+//   parentDomainPath: 'night',
+//   fullDomain: 'alice.night',
+//   depth: 1
+// }
+
+parseFullDomain('work.id.alice.night');
+// {
+//   isValid: true,
+//   domainName: 'work',
+//   parentDomainPath: 'id.alice.night',
+//   fullDomain: 'work.id.alice.night',
+//   depth: 3
+// }
+
+parseFullDomain('invalid');
+// {
+//   isValid: false,
+//   domainName: '',
+//   parentDomainPath: '',
+//   fullDomain: 'invalid.night',
+//   depth: 0
+// }
+```
+
+### isValidDomainName()
+
+Validates if a domain name follows the correct format rules.
+
+**Signature:**
+
+```typescript
+function isValidDomainName(domainName: string): boolean
+```
+
+**Rules:**
+
+- Length: 1-63 characters
+- Characters: lowercase letters (a-z), digits (0-9), hyphens (-)
+- Must start and end with a letter or digit (not hyphen)
+- No consecutive hyphens, dots, or special characters
+
+**Examples:**
+
+```typescript
+isValidDomainName('alice');        // true
+isValidDomainName('alice123');     // true
+isValidDomainName('alice-bob');    // true
+isValidDomainName('a');            // true
+isValidDomainName('123');          // true
+
+isValidDomainName('');             // false (empty)
+isValidDomainName('-alice');       // false (starts with hyphen)
+isValidDomainName('alice-');       // false (ends with hyphen)
+isValidDomainName('alice_bob');    // false (underscore not allowed)
+isValidDomainName('Alice');        // false (uppercase)
+isValidDomainName('alice bob');    // false (space not allowed)
+```
+
+<Aside type="note">
+  This function validates a single label, not a full domain. Use it to validate subdomain names before registration.
+</Aside>
+
+### getParentDomain()
+
+Returns the parent domain of a given domain.
+
+**Signature:**
+
+```typescript
+function getParentDomain(fullDomain: string): string | null
+```
+
+**Examples:**
+
+```typescript
+getParentDomain('alice.night');
+// => 'night'
+
+getParentDomain('work.id.alice.night');
+// => 'id.alice.night'
+
+getParentDomain('night');
+// => null (TLD has no parent)
+```
+
+### getSubdomain()
+
+Extracts the subdomain (leftmost label) from a full domain.
+
+**Signature:**
+
+```typescript
+function getSubdomain(fullDomain: string): string
+```
+
+**Examples:**
+
+```typescript
+getSubdomain('alice.night');
+// => 'alice'
+
+getSubdomain('work.id.alice.night');
+// => 'work'
+
+getSubdomain('night');
+// => 'night'
+```
+
+### buildFullDomain()
+
+Constructs a full domain from subdomain and parent parts.
+
+**Signature:**
+
+```typescript
+function buildFullDomain(subdomain: string, parent: string): string
+```
+
+**Examples:**
+
+```typescript
+buildFullDomain('alice', 'night');
+// => 'alice.night'
+
+buildFullDomain('work', 'id.alice.night');
+// => 'work.id.alice.night'
+
+buildFullDomain('', 'alice.night');
+// => 'alice.night' (empty subdomain returns parent)
+```
+
+### buildTraversalPath()
+
+Creates the path needed to traverse the domain hierarchy from TLD to the target domain.
+
+**Signature:**
+
+```typescript
+function buildTraversalPath(fullDomain: string, tld?: string): string[]
+```
+
+**Examples:**
+
+```typescript
+buildTraversalPath('alice.night');
+// => ['night', 'alice.night']
+
+buildTraversalPath('work.id.alice.night');
+// => ['night', 'alice.night', 'id.alice.night', 'work.id.alice.night']
+```
+
+This is useful for understanding how the SDK resolves domains internally.
+
+### isTLD()
+
+Checks if a domain is a top-level domain.
+
+**Signature:**
+
+```typescript
+function isTLD(domain: string, tld?: string): boolean
+```
+
+**Examples:**
+
+```typescript
+isTLD('night');        // true
+isTLD('night', 'night'); // true
+isTLD('alice.night');  // false
+```
+
+## Address Utilities
+
+Import from `@midnames/sdk/utils/address`:
+
+```typescript
+import {
+  bytesToHex,
+  formatContractAddress,
+  deriveShieldedAddress,
+  isWalletAddress,
+} from '@midnames/sdk/utils/address';
+```
+
+### bytesToHex()
+
+Converts a byte array to a hexadecimal string.
+
+**Signature:**
+
+```typescript
+function bytesToHex(bytes: Uint8Array): string
+```
+
+**Examples:**
+
+```typescript
+const bytes = new Uint8Array([0, 1, 255, 16]);
+bytesToHex(bytes);
+// => '0001ff10'
+```
+
+### formatContractAddress()
+
+Formats a contract address from raw bytes with the `0200` prefix.
+
+**Signature:**
+
+```typescript
+function formatContractAddress(bytes: Uint8Array): string
+```
+
+**Examples:**
+
+```typescript
+const contractBytes = new Uint8Array(32); // 32-byte contract ID
+formatContractAddress(contractBytes);
+// => '0200000000000000000000000000000000000000000000000000000000000000'
+```
+
+<Aside type="note">
+  Contract addresses in Midnight start with `0200` prefix, followed by 32 bytes in hex format.
+</Aside>
+
+### deriveShieldedAddress()
+
+Derives a full shielded address from a coin public key and encryption public key.
+
+**Signature:**
+
+```typescript
+function deriveShieldedAddress(
+  coinPublicKeyAddress: string,
+  encryptionPublicKey: string
+): string | null
+```
+
+**Parameters:**
+
+- `coinPublicKeyAddress` - A `mn_shield-cpk_test...` address
+- `encryptionPublicKey` - A `mn_shield-epk_test...` address
+
+**Returns:** A full shielded address (`mn_shield-addr_test...`) or `null` if invalid
+
+**Examples:**
+
+```typescript
+const cpk = 'mn_shield-cpk_test1abc...';
+const epk = 'mn_shield-epk_test1xyz...';
+
+const shieldedAddr = deriveShieldedAddress(cpk, epk);
+// => 'mn_shield-addr_test1...' or null
+```
+
+<Aside type="tip">
+  This is automatically used by the SDK when a domain has both a `CoinPublicKey` target and an `epk` field set.
+</Aside>
+
+### isWalletAddress()
+
+Checks if an address is a wallet address (vs contract address).
+
+**Signature:**
+
+```typescript
+function isWalletAddress(address: string): boolean
+```
+
+**Examples:**
+
+```typescript
+isWalletAddress('mn_shield-cpk_test1abc...');  // true
+isWalletAddress('mn_shield-addr_test1xyz...'); // true
+isWalletAddress('0200abc123...');              // false
+isWalletAddress('0xabc123...');                // false
+```
+
+## Common Patterns
+
+### Validate and normalize user input
+
+```typescript
+import { normalizeDomain, isValidDomainName } from '@midnames/sdk';
+
+function validateUserInput(input: string): string | null {
+  const normalized = normalizeDomain(input);
+  const parsed = parseFullDomain(normalized);
+
+  if (!parsed.isValid) {
+    return null; // Invalid format
+  }
+
+  if (!isValidDomainName(parsed.domainName)) {
+    return null; // Invalid domain name
+  }
+
+  return normalized; // Valid!
+}
+
+// Usage
+const domain = validateUserInput('Alice.Night');
+if (domain) {
+  console.log('Valid domain:', domain);
+  // => 'alice.night'
+}
+```
+
+### Build subdomain programmatically
+
+```typescript
+import { buildFullDomain, isValidDomainName } from '@midnames/sdk';
+
+function createSubdomain(parent: string, subdomain: string): string | null {
+  if (!isValidDomainName(subdomain)) {
+    return null; // Invalid subdomain name
+  }
+
+  return buildFullDomain(subdomain, parent);
+}
+
+// Usage
+const newDomain = createSubdomain('alice.night', 'work');
+// => 'work.alice.night'
+```
+
+### Parse and extract domain components
+
+```typescript
+import { parseFullDomain, getParentDomain, getSubdomain } from '@midnames/sdk';
+
+function analyzeDomain(fullDomain: string) {
+  const parsed = parseFullDomain(fullDomain);
+
+  if (!parsed.isValid) {
+    console.log('Invalid domain');
+    return;
+  }
+
+  console.log({
+    fullDomain: parsed.fullDomain,
+    label: getSubdomain(parsed.fullDomain),
+    parent: getParentDomain(parsed.fullDomain),
+    depth: parsed.depth,
+  });
+}
+
+analyzeDomain('work.id.alice.night');
+// {
+//   fullDomain: 'work.id.alice.night',
+//   label: 'work',
+//   parent: 'id.alice.night',
+//   depth: 3
+// }
+```
+
+### Check address types
+
+```typescript
+import { isWalletAddress } from '@midnames/sdk';
+
+function displayAddress(address: string) {
+  if (isWalletAddress(address)) {
+    console.log('This is a wallet address');
+    // Show user-friendly wallet UI
+  } else {
+    console.log('This is a contract address');
+    // Show contract explorer link
+  }
+}
+```
+
+## TypeScript Types
+
+All utility functions are fully typed. Import types when needed:
+
+```typescript
+import type { ParsedDomain } from '@midnames/sdk/utils/domain';
+
+function processDomain(parsed: ParsedDomain) {
+  if (parsed.isValid) {
+    console.log(`Valid: ${parsed.domainName}.${parsed.parentDomainPath}`);
+  }
+}
+```
+
+## Next Steps
+
+- Learn about [domain resolution](/reference/resolve/) to query domain data
+- Explore [domain operations](/reference/operations/) for write operations
+- Read the [error handling guide](/reference/types/#error-types) for error management
diff --git a/src/content/docs/reference/widget.mdx b/src/content/docs/reference/widget.mdx
index 4f01092..1b29e9b 100644
--- a/src/content/docs/reference/widget.mdx
+++ b/src/content/docs/reference/widget.mdx
@@ -1,4 +1,532 @@
 ---
-title: Domain Widget
-description: How to use widgets in your own site.
+title: Domain Profile Widget
+description: React component for displaying .night domain profiles
+sidebar:
+  label: Profile Widget
 ---
+
+import { Aside, Code } from "@astrojs/starlight/components";
+
+The `DomainProfileWidget` is a pre-built React component that displays rich domain profile information with customizable styling and behavior. Perfect for integrating domain profiles into your DApp, wallet, or social platform.
+
+## Features
+
+- **Automatic data fetching** - Just provide a domain name
+- **Rich profile display** - Avatar, banner, bio, social links
+- **Fully customizable** - Multiple variants, themes, and visibility controls
+- **Copy-to-clipboard** - Built-in address copying functionality
+- **TypeScript support** - Full type safety
+- **Responsive design** - Works on all screen sizes
+- **Error handling** - Graceful error states
+
+## Installation
+
+```bash
+npm install @midnames/sdk react react-dom lucide-react
+```
+
+The widget requires these peer dependencies:
+- `react` >= 18
+- `react-dom` >= 18
+- `lucide-react` >= 0.400.0
+
+## Basic Usage
+
+### Import the component and styles
+
+```tsx
+import '@midnames/sdk/styles.css';
+import { DomainProfileWidget } from '@midnames/sdk/react/DomainProfileWidget';
+import { createDefaultProvider } from '@midnames/sdk';
+
+function App() {
+  const provider = createDefaultProvider();
+
+  return (
+    <DomainProfileWidget
+      fullDomain="alice.night"
+      publicDataProvider={provider}
+    />
+  );
+}
+```
+
+<Aside type="tip">
+  Don't forget to import the styles! The widget requires `@midnames/sdk/styles.css` for proper rendering.
+</Aside>
+
+### Minimal example
+
+```tsx
+import '@midnames/sdk/styles.css';
+import { DomainProfileWidget } from '@midnames/sdk/react/DomainProfileWidget';
+
+// Uses the default TestNet provider
+function MyComponent() {
+  return <DomainProfileWidget fullDomain="alice.night" />;
+}
+```
+
+## Props Reference
+
+### Required Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `fullDomain` | `string` | The full domain name to display (e.g., `"alice.night"`) |
+
+### Optional Props
+
+#### Provider Configuration
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `publicDataProvider` | `PublicDataProvider` | TestNet provider | Custom Midnight network provider |
+
+#### Layout & Variant
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'full' \| 'compact' \| 'inline' \| 'minimal'` | `'full'` | Display variant (see examples below) |
+| `className` | `string` | - | Additional CSS classes |
+
+#### Visibility Controls
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `showStatus` | `boolean` | `true` | Show registration status badge |
+| `showBanner` | `boolean` | `true` | Show banner image if available |
+| `showAvatar` | `boolean` | `true` | Show avatar/profile picture |
+| `showBio` | `boolean` | `true` | Show biography text |
+| `showDomainInfo` | `boolean` | `true` | Show technical fields (owner, target, resolver) |
+| `showSocialLinks` | `boolean` | `true` | Show social media links |
+| `showCopyButtons` | `boolean` | `true` | Show copy-to-clipboard buttons |
+
+#### Field Selection
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `fields` | `Array<'target' \| 'owner' \| 'resolver'>` | `['target', 'owner', 'resolver']` | Which technical fields to display |
+| `customFields` | `string[]` | `[]` | Additional custom fields to show |
+
+#### Styling
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `theme` | `'light' \| 'dark' \| 'auto'` | `'auto'` | Color theme |
+| `borderRadius` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Corner rounding |
+| `padding` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Internal spacing |
+
+#### Event Callbacks
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `onError` | `(error: MidnamesError) => void` | Called when an error occurs |
+| `onFieldClick` | `(field: string, value: string) => void` | Called when a field is clicked |
+| `onCopySuccess` | `(field: string, value: string) => void` | Called after successful copy |
+| `renderActions` | `(data: DomainProfileData \| null) => ReactNode` | Custom action buttons/content |
+
+## Variants
+
+### Full (default)
+
+The complete profile card with all features enabled:
+
+```tsx
+<DomainProfileWidget
+  fullDomain="alice.night"
+  variant="full"
+/>
+```
+
+Shows: banner, avatar, name, domain, status, bio, technical fields, social links
+
+### Compact
+
+A condensed version without banner and reduced spacing:
+
+```tsx
+<DomainProfileWidget
+  fullDomain="alice.night"
+  variant="compact"
+/>
+```
+
+Shows: avatar, name, domain, status, bio (if available), technical fields
+
+### Inline
+
+Horizontal layout optimized for inline display:
+
+```tsx
+<DomainProfileWidget
+  fullDomain="alice.night"
+  variant="inline"
+/>
+```
+
+Shows: avatar, name, domain (side-by-side layout)
+
+### Minimal
+
+Just the essentials:
+
+```tsx
+<DomainProfileWidget
+  fullDomain="alice.night"
+  variant="minimal"
+/>
+```
+
+Shows: avatar, name
+
+## Customization Examples
+
+### Hide specific sections
+
+```tsx
+<DomainProfileWidget
+  fullDomain="alice.night"
+  showBanner={false}
+  showSocialLinks={false}
+  showStatus={false}
+/>
+```
+
+### Show only specific fields
+
+```tsx
+<DomainProfileWidget
+  fullDomain="alice.night"
+  fields={['target']}  // Only show target address
+  showSocialLinks={false}
+  showBio={false}
+/>
+```
+
+### Add custom fields
+
+```tsx
+<DomainProfileWidget
+  fullDomain="alice.night"
+  customFields={['discord', 'telegram', 'email']}
+/>
+```
+
+If these fields exist in the domain's custom fields, they'll be displayed.
+
+### Dark theme
+
+```tsx
+<DomainProfileWidget
+  fullDomain="alice.night"
+  theme="dark"
+  borderRadius="lg"
+  padding="lg"
+/>
+```
+
+### Custom styling
+
+```tsx
+<DomainProfileWidget
+  fullDomain="alice.night"
+  className="my-custom-widget"
+  borderRadius="none"
+  padding="sm"
+/>
+```
+
+Then in your CSS:
+
+```css
+.my-custom-widget {
+  border: 2px solid #6366f1;
+  box-shadow: 0 10px 30px rgba(99, 102, 241, 0.3);
+}
+
+.my-custom-widget .midnames-name {
+  color: #6366f1;
+  font-weight: 800;
+}
+```
+
+## Event Handling
+
+### Handle copy events
+
+```tsx
+<DomainProfileWidget
+  fullDomain="alice.night"
+  onCopySuccess={(field, value) => {
+    console.log(`Copied ${field}:`, value);
+    // Show a toast notification, etc.
+  }}
+/>
+```
+
+### Handle field clicks
+
+```tsx
+<DomainProfileWidget
+  fullDomain="alice.night"
+  onFieldClick={(field, value) => {
+    console.log(`Clicked ${field}:`, value);
+    // Navigate to block explorer, open modal, etc.
+  }}
+/>
+```
+
+### Handle errors
+
+```tsx
+<DomainProfileWidget
+  fullDomain="alice.night"
+  onError={(error) => {
+    console.error('Widget error:', error.code, error.message);
+    // Log to error tracking service
+  }}
+/>
+```
+
+### Custom actions
+
+```tsx
+<DomainProfileWidget
+  fullDomain="alice.night"
+  renderActions={(data) => {
+    if (!data?.info) return null;
+
+    return (
+      <div style={{ marginTop: '1rem', display: 'flex', gap: '0.5rem' }}>
+        <button onClick={() => sendMessage(data.fullDomain)}>
+          Send Message
+        </button>
+        <button onClick={() => sendPayment(data.resolvedTarget)}>
+          Send Payment
+        </button>
+      </div>
+    );
+  }}
+/>
+```
+
+## Profile Fields
+
+The widget automatically displays these fields if they exist:
+
+| Field | Displayed As | Location |
+|-------|--------------|----------|
+| `name` | Display name | Header |
+| `bio` | Biography text | Below header |
+| `avatar` | Profile picture | Header avatar |
+| `banner` | Header banner image | Top of card |
+| `website` | Clickable chip | Social links section |
+| `twitter` | "@username" chip | Social links section |
+| `github` | Username chip | Social links section |
+| `location` | Location chip | Social links section |
+| `epk` | Used for address derivation | Not displayed directly |
+
+## CopyableValue Component
+
+The widget includes a `CopyableValue` component that you can use independently:
+
+```tsx
+import { CopyableValue } from '@midnames/sdk/react/DomainProfileWidget';
+
+function MyComponent() {
+  return (
+    <CopyableValue
+      value="mn_shield-cpk_test1abc123..."
+      showCopy={true}
+      onCopySuccess={(field, value) => console.log('Copied!', value)}
+      fieldName="address"
+    />
+  );
+}
+```
+
+## Loading States
+
+The widget automatically shows a loading state while fetching domain data:
+
+```tsx
+<DomainProfileWidget fullDomain="alice.night" />
+// Shows: "Checking..." status while loading
+```
+
+## Error States
+
+If a domain doesn't exist or an error occurs:
+
+```tsx
+<DomainProfileWidget fullDomain="nonexistent.night" />
+// Shows: Error card with error details
+```
+
+You can handle errors programmatically:
+
+```tsx
+<DomainProfileWidget
+  fullDomain="alice.night"
+  onError={(error) => {
+    if (error.code === 'DOMAIN_NOT_FOUND') {
+      // Show "Domain available" UI
+    } else {
+      // Show error notification
+    }
+  }}
+/>
+```
+
+## Multiple Widgets
+
+Display multiple profiles easily:
+
+```tsx
+function DomainGallery() {
+  const domains = ['alice.night', 'bob.night', 'charlie.night'];
+
+  return (
+    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))', gap: '1rem' }}>
+      {domains.map(domain => (
+        <DomainProfileWidget
+          key={domain}
+          fullDomain={domain}
+          variant="compact"
+        />
+      ))}
+    </div>
+  );
+}
+```
+
+## Performance Tips
+
+### Use a shared provider
+
+```tsx
+import { createDefaultProvider } from '@midnames/sdk';
+
+const provider = createDefaultProvider();
+
+function MyApp() {
+  return (
+    <>
+      <DomainProfileWidget fullDomain="alice.night" publicDataProvider={provider} />
+      <DomainProfileWidget fullDomain="bob.night" publicDataProvider={provider} />
+      <DomainProfileWidget fullDomain="charlie.night" publicDataProvider={provider} />
+    </>
+  );
+}
+```
+
+### Lazy loading
+
+```tsx
+import { lazy, Suspense } from 'react';
+
+const DomainProfileWidget = lazy(() =>
+  import('@midnames/sdk/react/DomainProfileWidget').then(mod => ({
+    default: mod.DomainProfileWidget
+  }))
+);
+
+function MyComponent() {
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <DomainProfileWidget fullDomain="alice.night" />
+    </Suspense>
+  );
+}
+```
+
+## Complete Example
+
+Here's a full implementation showing common patterns:
+
+```tsx
+import { useState } from 'react';
+import '@midnames/sdk/styles.css';
+import { DomainProfileWidget } from '@midnames/sdk/react/DomainProfileWidget';
+import { createDefaultProvider } from '@midnames/sdk';
+
+function DomainProfilePage() {
+  const [domain, setDomain] = useState('alice.night');
+  const provider = createDefaultProvider();
+
+  return (
+    <div className="profile-page">
+      <input
+        type="text"
+        value={domain}
+        onChange={(e) => setDomain(e.target.value)}
+        placeholder="Enter domain..."
+      />
+
+      <DomainProfileWidget
+        fullDomain={domain}
+        publicDataProvider={provider}
+        variant="full"
+        theme="auto"
+        showCopyButtons={true}
+        onCopySuccess={(field, value) => {
+          console.log(`✅ Copied ${field}`);
+        }}
+        onError={(error) => {
+          console.error('Error loading profile:', error);
+        }}
+        renderActions={(data) => {
+          if (!data?.info) return null;
+
+          return (
+            <div className="profile-actions">
+              <button onClick={() => window.open(`https://explorer.midnight.network/address/${data.resolvedTarget}`)}>
+                View on Explorer
+              </button>
+            </div>
+          );
+        }}
+      />
+    </div>
+  );
+}
+
+export default DomainProfilePage;
+```
+
+## CSS Customization
+
+You can override widget styles using CSS:
+
+```css
+/* Change card background */
+.midnames-card {
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+}
+
+/* Customize name text */
+.midnames-name {
+  font-size: 2rem;
+  font-weight: 900;
+  text-shadow: 2px 2px 4px rgba(0, 0, 0, 0.2);
+}
+
+/* Style social links */
+.midnames-chip {
+  background: rgba(255, 255, 255, 0.2);
+  backdrop-filter: blur(10px);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+}
+
+/* Customize copy button */
+.midnames-copy-icon {
+  color: #6366f1;
+}
+```
+
+## Next Steps
+
+- Learn about [domain resolution](/reference/resolve/) for reading domain data
+- Explore [domain operations](/reference/operations/) for write operations
+- Check out [utility functions](/reference/utils/) for helper functions