diff --git a/doc/BINPKG_INFO.txt b/doc/BINPKG_INFO
similarity index 53%
rename from doc/BINPKG_INFO.txt
rename to doc/BINPKG_INFO
index a97f2e80294..e4ec150a22e 100644
--- a/doc/BINPKG_INFO.txt
+++ b/doc/BINPKG_INFO
@@ -1,5 +1,5 @@
 A binary package built with xbps is a normal tar(1) archive, compressed
-with gzip, bzip2 or lzma and has the following structure:
+with bzip2 and has the following structure:
 
 	/
 	/usr ------|
@@ -19,10 +19,29 @@ install. The props.plist file is a proplib(3) property list and
 has the following structure:
 
 <dict>
+	<key>pkgname</key>
+	<string>foo</string>
+
+	<key>version</key>
+	<string>3.40</string>
+
+	<key>maintainer</key>
+	<string>The Master BOFH <bofh@baobab.org> </string>
+
+	<key>short_desc</key>
+	<string>Foo is a virtual package</string>
+
+	<key>long_desc</key>
+	<string>
+ Foo is a virtual package to show how the metadata props.plist file works
+ with xbps handling binary packages.</string>
+
 	<key>architecture</key>
 	<string>x86_64</string>
+
 	<key>installed_size</key>
 	<integer>500000</integer>
+
 	<key>configuration_files</key>
 	<array>
 		<string>/etc/foo.conf</string>
@@ -31,12 +50,16 @@ has the following structure:
 	<key>run_depends</key>
 	<array>
 		<string>bofh-2.0</string>
-		<string>foof-1.1</string>
+		<string>blab-1.1</string>
 		...
 	</array>
+	...
 </dict>
 
-This plist might be extended in the future if it's required or useful.
+This plist might be extended in the future; additional scripts might be
+added to trigger actions at pre/post installation/removal of the
+binary package.
 
-Additional scripts might be added to trigger some actions at pre/post
-installation stages.
+The package's dictionary will also be written into the repository's package
+index file, that describes information about a binary package on it.
+See the BINPKG_REPOSITORY file for more info about repositories.
diff --git a/doc/BINPKG_REPOSITORY b/doc/BINPKG_REPOSITORY
new file mode 100644
index 00000000000..fbd1874a07b
--- /dev/null
+++ b/doc/BINPKG_REPOSITORY
@@ -0,0 +1,43 @@
+A repository for binary packages contains the packages itself, and
+an index file describing the information about available packages.
+
+The structure for this file is just the same than the plist file used
+to register installed packages, aka "an array of dictionaries" and
+a "dictionary per package".
+
+The package dictionary will be the same than the one available in
+package's metadata directory "/var/cache/xbps/$pkgname/props.plist",
+but some additional objects are added to provide enough info for
+the repository itself.
+
+Here's how the package index plist file shall look like in a repository:
+
+<dict>
+	<key>xbps_available_packages</key>
+	<array>
+		<dict>
+			<key>pkgname</key>
+			<string>klibc</string>
+			<key>version</key>
+			<string>1.5.17</string>
+			<key>filename</key>
+			<string>klibc-1.5.17.x86_64.xbps</string>
+			<key>architecture</key>
+			<string>x86_64</string>
+			<key>installed_size</key>
+			<integer>9471141</integer>
+			<key>maintainer</key>
+			<string>Juan RP xtraeme@gmail.com</string>
+			<key>short_desc</key>
+			<string>Minimal libc subset for use with initramfs</key>
+			<key>long_desc</key>
+			<string>
+ klibc is intended to be a minimalistic libc subset for use with initramfs.
+ It is deliberately written for small size, minimal entanglement, and
+ portability, not speed. It is definitely a work in progress and a lot of
+ things are still missing.</string>
+			...
+		</dict>
+		...
+	</array>
+</dict>