diff --git a/README.md b/README.md
index 8be1ed3..5fd4c33 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,148 @@
 # @agape/metadata
 
-Metadata annotations
+Metadata annotations and descriptors for TypeScript classes, properties, methods, and parameters.
 
-## Author
+## ✨ Decorators
 
-Maverik Minett  maverik.minett@gmail.com
+### `@Description(text)`
+Attaches human-readable descriptions to classes, properties, methods, or parameters.
 
-## Copyright
+### `@Label(singular, plural?)`
+Provides display labels for UI components and documentation.
 
-© 2025 Maverik Minett
+### `@Name(name)`
+Specifies custom names for serialization and identification.
 
-## License
+### `@Sensitive(flag?)`
+Marks elements as containing sensitive data (defaults to `true`).
 
-MIT
+### `@Token(singular, plural?)`
+Associates tokens with elements for external system integration.
+
+### `@Noun(singular, plural?)`
+Defines grammatical nouns for natural language processing.
+
+### `@Example(value)`
+Provides example values for documentation and validation.
+
+---
+
+## 🚀 Example
+
+```ts
+import { Description, Label, Sensitive, Token, Noun, label, description, tokens } from '@agape/metadata';
+
+@Label('User')
+@Token('user')
+@Noun('user', 'users')
+@Description('User account with authentication and profile information')
+class User {
+  
+  @Label('User ID')
+  @Description('Unique identifier for the user')
+  id!: number;
+  
+  @Label('Email Address')
+  @Description('The user\'s email address for login and notifications')
+  @Sensitive()
+  email!: string;
+
+  @Label('Full Name')
+  @Description('The user\'s full name as displayed on their profile')
+  fullName!: string;
+
+  @Label('Created At')
+  @Description('Account creation timestamp')
+  createdAt!: Date;
+}
+
+// Use metadata in your application
+const content = `
+<h2>Edit ${label(User)}</h2>
+<div>${description(User)}</div>
+<form class="${tokens(User)}">
+  <label for="fullName">${label(User, 'fullName')}</label>
+  <input type="text" id="fullName" name="fullName" />
+  
+  <label for="email">${label(User, 'email')}</label>
+  <input type="email" id="email" name="email" />
+</form>
+`;
+```
+
+---
+
+## 🔧 Functions
+
+### `description(target, property?, index?)`
+Retrieves the description metadata for a class, property, or parameter.
+
+### `name(target, property?, index?)`
+Retrieves the name metadata for a class, property, or parameter.
+
+### `label(target, property?, index?)`
+Retrieves the label metadata for a class, property, or parameter.
+
+### `sensitive(target, property?, index?)`
+Checks if a class, property, or parameter is marked as sensitive.
+
+### `token(target, property?, index?)`
+Retrieves the token metadata for a class, property, or parameter.
+
+### `noun(target, property?, index?)`
+Retrieves the noun metadata for a class, property, or parameter.
+
+### `example(target, property?, index?)`
+Retrieves the example metadata for a class, property, or parameter.
+
+### `labels(target, property?, index?)`
+Retrieves the plural label for a class, property, or parameter.
+
+### `tokens(target, property?, index?)`
+Retrieves the plural token for a class, property, or parameter.
+
+### `nouns(target, property?, index?)`
+Retrieves the plural noun for a class, property, or parameter.
+
+---
+
+## 🏗️ MetadataDescriptor
+
+### `MetadataDescriptor.for(target, property?, index?)`
+Creates or retrieves a metadata descriptor for a class, property, or parameter.
+
+### `MetadataDescriptor.get(target, property?, index?)`
+Retrieves an existing metadata descriptor for a class, property, or parameter.
+
+### Example
+```ts
+import { MetadataDescriptor } from '@agape/metadata';
+
+// Get descriptor for a property
+const descriptor = MetadataDescriptor.for(User, 'email');
+
+// Access all metadata properties
+console.log(descriptor.description);  // "The user's email address..."
+console.log(descriptor.label);        // "Email Address"
+console.log(descriptor.name);         // "email"
+console.log(descriptor.sensitive);    // true
+console.log(descriptor.token);        // "user.email"
+console.log(descriptor.noun);         // "email"
+console.log(descriptor.nouns);        // "emails"
+console.log(descriptor.example);      // "john.doe@example.com"
+
+// Set metadata directly
+descriptor.description = "Updated description";
+descriptor.sensitive = false;
+```
+
+---
+
+## 📚 Documentation
+
+See the full API documentation at [agape.dev/api](https://agape.dev/api).
+
+
+## 📦 Agape Toolkit
+
+This package is part of the [Agape Toolkit](https://github.com/AgapeToolkit/AgapeToolkit) - a comprehensive collection of TypeScript utilities and libraries for modern web development.
diff --git a/package.json b/package.json
index 515f4ae..e8167c0 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@agape/metadata",
-  "version": "0.2.0",
+  "version": "0.1.0",
   "description": "Metadata annotations",
   "main": "./cjs/index.js",
   "module": "./es2020/index.js",
@@ -12,9 +12,10 @@
   "publishConfig": {
     "access": "public"
   },
+  "homepage": "https://agape.dev",
   "repository": {
     "type": "git",
-    "url": "https://github.com/AgapeToolkit/AgapeToolkit"
+    "url": "https://github.com/AgapeToolkit/meta-data"
   },
   "keywords": [
     "agape",
@@ -34,4 +35,4 @@
       "import": "./es2020/index.js"
     }
   }
-}
\ No newline at end of file
+}